The custom placeholders feature enables you to create your very own placeholders that can be detected upon translation files importing and exporting. This feature will come in very handy if, for example, you're using non-standard placeholders in your files or placeholders that are not properly recognized by Lokalise.

For example, suppose you have a JSON file with the following data:

The welcome key uses a {%username%} placeholder which won't be detected properly by Lokalise as it's non-standard (however it may happen that we also don't support certain standard placeholders for some file formats):

As you can see, the curly brackets were not detected as part of the placeholder. It can pose a serious problem when translating this string manually and especially when using machine translation. However, this issue can be easily fixed by creating a custom placeholder!

To get started with the custom placeholders feature, open your Lokalise project and proceed to Apps:

Then find the Custom placeholders item in the list (or use the search box) and click on it:

Then click Install.

Now you'll need to enter the opening and closing characters as well as the file format (or simply choose All formats):

For example, I'm going to enter {% and %}, and choose the JSON file format.

Once you are ready, click the Enable app button.

Now if you try to upload a translation file with custom placeholders in place, you'll notice that these are properly displayed in the editor:

Under the hoods, we convert these into Lokalise universal placeholders.

The %s part simply means "a string". Next, you'll be able to export your data in any format and these universal placeholders will be replaced back with your custom ones.

To export translations with custom placeholders, navigate to the Download page and choose the desired file format:

Then make sure to choose Raw from the Placeholder format dropdown:

Finally click Build and download. You'll see that Lokalise universal placeholders are replaced with the platform-specific ones once again!

This feature does not work with the Offline translations (in XLIFF format)

When importing files, some formats are automatically grouped into more general categories. For example:

This happens because the system infers the format on import instead of requiring you to select it (except when using paste-based import, where you manually pick the format).

Let’s say you choose PHP Laravel array as your format and import a .php file. If custom placeholders don’t work as expected, it’s likely because the system treated the file as a regular PHP array, not a Laravel array. A similar issue can happen if you select Structured JSON but upload a normal .json file—the system may not apply the expected format settings.

Therefore, if you need to work with specific formats like PHP Laravel array or Structured JSON, make sure to select All supported formats when configuring custom placeholders.