Keys and files belong to translation projects therefore if you are not familiar with Lokalise projects, it's really recommended to check out the Project article. Specifically, we'd advise skimming through the Learn how platforms, keys, and files are organized section to understand how exactly your data is hosted and represented on Lokalise.
In this article you'll learn how to download translation files from Lokalise back to your PC, fire app triggers and webhooks.
What are translation files?
Translation files contain translation data in a predefined format. This data can then be utilized in an application, website, or a game. In many cases translation files are organized in a key-value format where every key has a corresponding translation value. Such files are typically utilized in mobile apps and websites. However, it's also possible to store your translations in regular .docx files, spreadsheets, presentations, and even HTML files.
Getting started
To get started with the project exporting, click the Download button in the main menu:
If your project has quality assurance problems, you will see a warning message. Click the QA issues link to see what problems were found. In the example below, it says that there are unreviewed and unverified translations as well as discrepancy related to the HTML tags:
You will probably want to resolve all the QA issues before proceeding, but this step can be skipped. Learn more about QA issues.
Please remember that Lokalise does not keep file templates as such. Once your file is uploaded to the platform, translation keys are extracted into your project. A brand new file will be generated upon project export.
Selecting file format
In the File format dropdown menu, you can select file export formats. We support more than 20 file formats; please check the full list of supported formats here.
File formats are grouped by platforms (Web, iOS, Android, Other) and by default only the keys that are assigned to the corresponding platform will be included in the download bundle. If you would like to export keys for all platforms in the specified format, tick the Include all platform keys checkbox. You can learn more about keys and platforms in the corresponding article.
Selecting languages and file structure
Expand the Language section to choose which languages should be included in the download bundle. All languages are selected by default but you can pick only the required ones:
Next to the language names you can see the overall translation progress.
Click on the language ISO code to override it:
Check the Language settings article to learn more about language ISO codes.
The next step is selecting the file structure:
The following placeholders are supported when defining your file structure:
%LANG_ISO%— a placeholder that will be replaced with a specific language code.%FORMAT%— a placeholder that will be replaced with the file format.%LANG_NAME%— a placeholder that will be replaced with a language's name.%PROJECT_NAME%— a placeholder that will be replaced with a project's name.
The One file per language option means that all your translations will be separated by their language, and placed into a single file. Note that you can also modify the file structure and even provide a directory prefix using / (forward slash) as shown in the image above.
Alternatively, you may choose the Multiple files per language option. Select this option when your translation keys were previously assigned to filenames, and you would like to preserve this structure. Learn more about filenames and their usage in the corresponding article.
Please note that if you choose Multiple files per language option and there are keys that are not assigned to any filename, these unassigned keys will be exported to a file called no_filename.%FORMAT%.
Selecting keys/translations to download
Next, let's expand the Content to export section:
Data
All — the default value which means "export all translation keys".
Untranslated strings — download only the strings that are not translated.
Translated strings — download only the strings that have been translated.
Reviewed only strings — download only the strings that were reviewed.
Last reviewed strings — download only the previously reviewed translations. For example, suppose we have a reviewed translation “Hello World”. Then someone has changed this translation to “Hello worlds!”, and the new version has not been reviewed yet. In this case, the previously reviewed version of the translation (“Hello World”) will be exported.
Verified strings — download only the strings that were verified.
Non-hidden keys — download only the keys that were not hidden from project contributors.
Include tags — this text field allows you to filter the translation keys by their tags. For example, if we choose “demo”, only the keys under this tag will be exported.
Exclude tags — this field is used to enter tags that you wish to exclude. All keys under the chosen tags will not be downloaded.
File name — only the keys linked to the chosen filenames will be exported. If you leave this field empty, keys from all files, as well as keys not assigned to any filenames, will be exported.
Advanced settings
Next, expand the Advanced settings section. Please note that these settings will vary depending on the chosen file format:
Include comments — key comments will be exported along with the translation data. Please note that this setting will be available only if the output format actually supports commenting. Also note that it's not possible to export replies and translation-level comments. In other words, only the parent comments can be exported.
Include description — export key descriptions if it is supported by the output format.
Don’t use directory prefix — this checkbox will only appear if you have selected the Multiple files per language option in the File structure section. If this option is unchecked, Lokalise will place translation files inside folders named after a specific locale. For example, French translations will be placed inside the
frfolder. When this option is checked, Lokalise will strictly follow the directory structure specified in the File structure section. If you enable this option, don’t forget to provide the%LANG_ISO%placeholder in the filenames. If you forget to do so, all files with the same names will be overwritten.Disable referencing — when this option is enabled, all referenced translations will be exported as raw references (for example,
[%key_id:12345%]) instead of the actual value. Learn more about the Key referencing here.Replace line break with
\n— all line breaks in your translations will be replaced with a special\ncharacter, which means “start the text after this symbol on a new line”. Note that when the translation file is being imported to Lokalise, the reverse process may happen and all\ncharacters can be replaced with the line breaks.Language code as the root key — this option is available for certain file formats only, for instance YAML. When this setting is enabled, your translation keys will be nested under a parent key named after a language code.
Unescape forward slashes — this option will become visible when JSON formats are selected. When this setting is enabled, forward slashes (
/) will be unescaped.Add new line at EOF — turn this option on to add a new line at the end of your translation files (supported formats: JSON, PHP).
Empty translations — using this option you can choose what to do with the keys that have no translations. The default action is to export and assign empty strings as the translation values. You can also choose not to export these keys at all, or provide the base language as a value. Certain file formats may have additional options.
Order keys by — select how to organize your keys in the exported file.
Plural format — choose the formatting for your plural keys. The available options will vary depending on the file format you have chosen.
Placeholder format — choose the output formatting of your placeholders. The available options may change depending on the file format you have chosen.
Convert all
[%]to%%—[%]is a special Lokalise placeholder. When this option is enabled it will be exported as%%.Indentation — how many spaces should be used to indent your nested keys. Usually, 2 spaces represent one level of indentation, but you may choose any value from one to eight. Also, it is possible to choose Tab, which means one indentation level equals to the
Tabkey pressed once, but this is not generally recommended.
Include other project strings
Select other projects whose keys and translations should be added to the download bundle. If previously (in the Content to export section) you've chosen tags to include or exclude, this selection will apply to all other included projects. This feature is useful if you share similar keys over several projects (for example, country names).
Please note that when selecting multiple projects, Lokalise will not filter duplicate keys and only include languages selected above (if the chosen languages actually present in the included projects). It means that if the same key is present in multiple projects, only one instance of this key and its translations will actually be exported, and we cannot predict which instance will be included in the download bundle.
App triggers
In this section, you can choose one or more platforms to export your data to. Before any of these triggers can be chosen, you have to configure them properly in project settings under the Apps tab. Learn more about available integrations here.
Webhook triggers
Choose a webhook to fire once the export process is finished. Webhooks are used to perform certain actions once a specified process is completed successfully. Learn more about webhooks in the corresponding article on our DevHub.
Starting the download process
When you have reviewed all the settings, you can build and download your files. Note that these download settings are saved on a per-user basis. It means that other project contributors will have their own settings and won’t be affected by the changes you apply on this page.
Click Build and download to get an archive with all the chosen translation data. It is possible to perform Build only without downloading anything — this is very useful in cases when you would like to run the app triggers (for example, GitHub or Bitbucket integration). Finally, you can click the Preview button to see your data directly inside the browser. This is very helpful for testing and debugging purposes.