Uploading translation files

Learn how to upload your translation files to Lokalise.

Ilya Krukowski avatar
Written by Ilya Krukowski
Updated over a week ago

In this article you'll learn how to upload translation files to Lokalise.

Note: 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 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.

Getting started

To get started, open your translation project and proceed to the Upload page:

Alternatively you can use our CLI, API, or apps to upload translation data.

Here's the Upload page:

If you are looking for CLI upload/download scenarios, please check the Filenames article.

Choosing data to upload

To upload one or more files, click Select a file and choose them from your PC. You can also drag'n'drop files to the uploading area.

To upload a whole directory, you can either click Select a file and choose this directory, or drag'n'drop it to the uploading area.

Finally, you can click Copy-paste data and place file contents into the text box:

Once you've chosen translation files to upload, they will be displayed in the following way:

You can see the following info:

  • Original filename. Please note that Lokalise detects language ISO portions in the filenames and highlights them with green. These language ISO parts will automatically be replaced with the %LANG_ISO% placeholder upon importing. When translations are downloaded back, Lokalise will replace these placeholders with the corresponding language ISO codes. To learn about filenames and their usage, please refer to the corresponding article.
    You can adjust the filename by clicking on it:


  • File format.

  • Number of detected translation keys and the words count.

  • Detected language. Lokalise will detect the language automatically either by reading language settings inside the uploaded file or by using Google Translate. If the language was detected improperly, you can adjust it manually by clicking on the corresponding dropdown.

Upload options

There are a handful of upload options that you may enable or disable as needed:

  • Replace \n with line break — in some programming environments a new line in the text is marked with a \n character. It simply means that the text after this character should start with a new line. But you might want to get rid of \n and turn it into line breaks inside the Lokalise project editor so that translators are not confused. When you are going to export translations back, these line breaks can be replaced with \n once again.

  • Convert to universal placeholders — sometimes in your translations you may use special placeholders to represent a dynamically inserted value. You will probably want to store all platform keys in a single Lokalise project. However, each platform (say, Web or Android) requires placeholders to be written in a specific way. Conveniently, Lokalise allows to convert these placeholders into a universal format. When you export your translation files, these universal placeholders will be replaced back with platform-specific ones.

  • Detect ICU plurals — ICU is a special library for internationalization. ICU’s special format for plurals is widely used for representing word’s declension depending on some variable count. If you enable this option, Lokalise detects ICU expressions and shows them in the interface. To learn more about ICU message format, please check out our blog post.

  • Tag keys — if you would like to tag the affected translation keys, enable this option. Choose the existing tags or enter new ones. Then decide which keys should be tagged: inserted (newly created ones), updated (existing ones with the values being updated), or skipped (existing ones that were not modified).

  • Differentiate keys by file — enable this option if you don’t want to merge similar keys from different files. Remember that in Lokalise you are not working directly with the uploaded files. The platform extracts information from your files, parses it, stores it inside the system and exports it on demand by generating files again.

  • Fill empty keys with key names — if some keys do not have any value yet, the key itself will act as a value. You may update that value later, of course.

  • Hide from contributors — if you would like to make the newly added keys invisible to the project’s contributors, enable this option. In this case the keys will be visible to project admins only. Later the hidden keys can be made visible to everyone.

  • Custom translation statuses — this option will become visible only if you have enabled custom translation statuses feature in your project settings. When this option is checked, you'll be able to select which statuses should be assigned to inserted, updated, or skipped keys.

  • Enable automations — use automations for the uploaded keys. To learn more about automations, please check the corresponding documentation.

  • Pre-translate with 100% TM matches — while doing translations, you will probably find yourself in a situation when you are starting to translate the same phrases and sentences. Lokalise remembers your translations and analyzes matches between the text you have already translated and text from the uploaded file. If the system detects a 100% match, it will automatically translate keys in the files you’ve uploaded.

    • Please note that this feature cannot be used in conjunction with the Enable automations option. If you need to pre-translate the uploaded texts and apply some automation logic, create a special automation action Apply translation memory > with threshold 100%, and tick only the Enable automations setting.

  • Replace modified values — suppose you are uploading a translation file which has a handful of translation keys that were already added to the project. By default, Lokalise uploader will keep the values under such keys intact. However, if you do want to update translations under already existing keys, enable this option.

    • Please note that when this feature is enabled, it replaces both key translations and descriptions (if the uploaded file contains key descriptions, that is).

    • When this feature is enabled, it does not replace the context field.

  • Enable cleanup mode — when this option is enabled, Lokalise will delete all keys with their translations that are not found in the uploaded file. Be careful with this option! Before the upload happens, you will be asked to confirm deletion for extra protection. Please note that this mode takes filenames and platforms into consideration. Suppose, your project contains multiple keys assigned to a file named %LANG_ISO%.json and a handful of keys not assigned to any filename. If you upload a %LANG_ISO%.yml file containing new keys, all existing entries will be preserved as they are assigned to a different file (or not assigned to any file at all). However, existing entries assigned to the %LANG_ISO%.yml file will be removed.

Starting the upload

When all filenames and languages look correct, adjust the upload settings and click Import the files. The upload process will be performed in the background so you may navigate to another page. Please note that all the missing languages will be created in your project automatically. For example, if you are uploading Latvian translation but your project does not have Latvian language, it will be added for you (this, however, is not the case when uploading translation files via the API).

To view the status of your upload click More > Activity in the main menu.

Active processes tab lists all the currently running imports and other jobs. You may cancel the process by clicking the Cancel button.

Once the import finishes, the corresponding job will be moved under the Finished processes tab.

Click on a process to see more details:

  • What files were imported.

  • How many keys were inserted, updated, and skipped.

  • What languages were imported.

  • Status for each file.

To remove all finished processes from the list, press Clear. Please note, that all finished processes older than 48 hours will be automatically cleared from the list.

Custom language codes

If you are using a custom language code, e.g. sk-SK instead of the standard sk, please do the following after the upload succeeds:

  • Go to your project.

  • Click on the language dropdown, find your language, and click on small dots next to its name.

  • Choose Settings.

  • Enable the Custom language code switch.

  • Set the desired language code.

Please find more information in the Language settings article.

Did this answer your question?