Skip to main content
Uploading translation files

Learn how to upload your translation files to Lokalise.

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

In this article, you’ll learn how to upload your translation files to Lokalise.

Keys and files are integral parts of translation projects in Lokalise. If you’re new to Lokalise projects, we highly recommend checking out the Projects article. Pay particular attention to the section on how platforms, keys, and files are organized to get a clear understanding of how your data is hosted and represented in Lokalise.

Note on project types and supported file formats

Before proceeding, ensure you’ve selected the correct project type for your content. The project type is chosen during creation and cannot be changed later. Your interface may vary slightly depending on the project type, and certain options might not be available.

For a complete list of supported file formats, check out the Supported file formats collection.

Key-based file formats and developer tools

Key-based translation files (e.g., JSON, XML, YAML, Excel) can only be uploaded to Web and Mobile projects.

If you're integrating with services like GitHub or Bitbucket, also use Web and Mobile projects, but refer to the specific app’s instructions.

Non-key-based file formats

Formats that don’t use translation keys, such as DOCX, HTML, and IDML, should be uploaded to Ad hoc documents projects.

While Lokalise doesn’t support DOC or PDF formats directly, you can order professional translations via Gengo, adding such files to the order, though there are limitations.

Translations from content management services

For third-party content management tools like Contentful, Marketo, or Intercom Articles, use Marketing and support projects. In these cases, you won’t manually upload files; instead, run an import process as explained in the Marketing and support project type article.


Accessing the Upload page

To get upload key-based or non-key based files, open your translation project and proceed to the Upload page:

To upload key-based or non-key-based files, open your translation project and go to the Upload page. Alternatively, you can use our CLI, API, or apps to upload translation data.

For Web and mobile projects, the Upload page offers a variety of options:

For Ad hoc documents projects, the interface is similar but with fewer options. Marketing and support projects do not have an Upload page; instead, manage content under the Content management tab.

For specific upload/download scenarios, refer to the Filenames article.


Choosing data to upload

To upload files:

  • Click Select a file and choose files from your PC, or drag and drop them into the upload area.

  • To upload a directory, select it through the UI or drag and drop it into the upload area.

  • Alternatively, click Copy-paste data and paste file contents into the text box:

Once you select files, they’ll be displayed with the following details:

You can see the following info:

  • Original filename: Lokalise detects language ISO codes in filenames and highlights them. These will be replaced with the %LANG_ISO% placeholder upon import and substituted back with the actual language codes when exporting.
    You can adjust the filename by clicking on it:

  • File format.

  • Number of detected translation keys and word count.

  • Detected language: Lokalise auto-detects the language or uses Google Translate. If incorrect, you can manually adjust it.


Upload options

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

  • Replace \n with line break — converts \n characters into actual line breaks within the Lokalise project editor. This makes the text easier for translators to read. When exporting, these line breaks can be converted back to \n.

  • Convert to universal placeholders — in your translations, you might use special placeholders to represent dynamically inserted values. When working across multiple platforms, such as Web and Android, each platform may require these placeholders to be formatted differently. To streamline this, Lokalise allows you to store all platform keys within a single project and automatically converts these placeholders into a universal format. When you export your translation files, Lokalise will then convert these universal placeholders back into the platform-specific formats required by each platform.

  • Detect ICU pluralsICU (International Components for Unicode) provides a standard for handling plurals and other language-specific variations. Enabling this option allows Lokalise to recognize and display ICU plural expressions correctly. To learn more about ICU, please check our Complete guide to ICU message format.

  • Tag keys — you can tag the keys affected by your upload. Choose existing tags or create new ones, and decide whether to tag newly created, updated, or skipped keys.

  • Differentiate keys by file — this option prevents merging keys with the same name across different files. It’s useful if you need to keep similar keys separate based on their original files.

  • Fill empty keys with key names — if a key doesn’t have a value, the key name itself will be used as the value. You can update these values later.

  • Hide from contributors — make newly added keys visible only to project admins. These keys can be made visible to contributors later.

  • Custom translation statuses — if custom translation statuses are enabled in your project settings, this option lets you assign specific statuses to inserted, updated, or skipped keys during the upload process.

  • Enable automations — apply any existing automations to the uploaded keys. For more details, refer to the Automations documentation.

  • Pre-translate with 100% TM matches — Lokalise checks your translation memory (TM) for 100% matches and automatically applies these translations to the uploaded keys. Note that this feature cannot be used simultaneously with Enable automations.

    • 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 an automation action Apply translation memory > with threshold 100%, and tick only the Enable automations setting mentioned above.

  • Replace modified values — if you're uploading a translation file that includes keys already present in the project, the Lokalise uploader, by default, will keep the existing values for those keys unchanged. However, if you want to update the translations for these existing keys, you can enable the Replace modified values option.

    • This feature replaces both key translations and descriptions (if the uploaded file contains key descriptions, that is).

    • This feature doesn't replace the context field.

  • Enable cleanup mode — when this option is enabled, Lokalise will delete any keys and their translations that are not found in the uploaded file. This is a powerful feature, so use it with caution! Before the upload is finalized, Lokalise will prompt you to confirm the deletion to ensure you don’t accidentally remove important data.

    • Cleanup mode takes filenames and platforms into account. For instance, if your project has multiple keys assigned to a file named %LANG_ISO%.json and other keys that aren’t assigned to any file, uploading a %LANG_ISO%.yml file with new keys will only affect entries related to the .yml file. The existing keys assigned to the .json file or unassigned keys will remain unchanged, while any existing entries assigned to the %LANG_ISO%.yml file will be removed if they are not included in the uploaded file.


Starting the upload and viewing upload progress

Once all filenames, languages, and settings are correct, click Import the files to start the upload. The process runs in the background, allowing you to continue working or navigate to another page.

If your project doesn’t already include a language found in the uploaded files, Lokalise will automatically add it (note: this does not apply to uploads via API).

To monitor your upload’s progress, go to More > Activity in the main menu:

The Active processes tab shows all current uploads and other tasks, where you can cancel them if needed.

Once the upload is complete, it will move to the Finished processes tab.

Click on any finished process to view detailed information:

  • Imported files

  • Number of keys inserted, updated, and skipped

  • Imported languages

  • Status of each file

You can clear all finished processes from the list by pressing Clear. Note that processes older than 48 hours are automatically removed from the list.


Custom language codes

If you’re using a custom language code (e.g., sk-SK instead of the standard sk), follow these steps after the upload:

  1. Open your project.

  2. Click the language dropdown, find your language, and click the three dots next to its name.

  3. Select Settings.

  4. Enable the Custom language code option.

  5. Enter your desired custom language code.

For more information, refer to the Language settings article.

Did this answer your question?