In this article, you’ll explore how to effectively manage filenames on Lokalise.

For details on supported file formats, please check out our File formats collection.

Introduction

Lokalise doesn’t store files or templates in their original form. Instead, when you upload translation files, Lokalise parses them to extract keys and values (or textual information from DOCX, HTML, and other non-key based files), which are then saved in its database. While the original files aren't stored as-is, Lokalise does keep a record of their filenames to track which keys belong to which files.

When you download translations, Lokalise generates files dynamically in your preferred format. This process offers flexibility—you can either keep the original file structure and names or organize them in a completely new way. You can also easily rename files or reassign keys to different files as needed.

Filenames and file uploading

When working with Lokalise, remember that key-based translation files (like JSON, XML, YAML) can only be uploaded to Web and mobile projects. Formats that don’t use translation keys, such as DOCX, HTML, and IDML, should be uploaded to Ad hoc documents projects. If you need to integrate with third-party tools like Contentful, Marketo, or Intercom Articles, use Marketing and support projects.

Learn more about project types in the Projects article.

Let’s see how filenames are stored in Lokalise when you upload translation files. Suppose you have two files named main-en.json and main-lv.json.

main-en.json:

{
  "welcome": "Welcome to the app!",
  "how_are_you": "How are you doing?"
}

main-lv.json:

{
  "welcome": "Laipni lūdzam lietotnē!",
  "how_are_you": "Kā tev iet?"
}

Go to the Upload page, click Select a file, and choose these two files.

You can click on the filename to adjust it:

Lokalise automatically detects the en language ISO code and replaces it with the %LANG_ISO% placeholder. This is a handy feature, so it’s recommended to keep this placeholder in the filename.

After clicking Import files and returning to the project editor, you’ll see main-%LANG_ISO%.json under key names.

Since the original filenames followed the same pattern with language ISO codes, Lokalise assigned all keys to a single "universal" filename for convenience.

Are the original filenames lost? Not at all! When you download translations back to your computer, you can replace the %LANG_ISO% placeholder with the actual language code.

You can also click on the filename under the key name to filter and display only the keys associated with that specific file.

Files widget

To view all translation files in your project, open the Files widget from the top menu:

You’ll see a dialog displaying the files in your project:

In this example, our project contains two files.

Use the search box to find a file by its name.
Click on a filename to display only the keys assigned to that file.
Click the three dots next to a filename to rename it or set custom data.

Custom data will be exported along with your translations if the output file format supports storing additional data.

Assigning keys to filenames

To edit translation key details, contributors need the appropriate permissions, and key editing must be enabled in your project. To enable this, go to project settings and ensure the Allow key editing option is set to All properties.

You can assign or unassign existing keys to/from filenames within the key editor. To access the key editor, click on the key name:

In the key editor, go to the Advanced tab and locate the Assigned to file section.

Keep in mind that file assignment is done on a per-platform basis.

File assignment and key platforms

Lokalise supports four platforms: Web, iOS, Android, and Other. Each key must be assigned to at least one platform, which determines if the key will be included in the download bundle based on the chosen output file format.

For example, if a key belongs to the Web platform and you export translations in JSON format, this key will be included in the bundle (since JSON is popular for Web). However, if you choose the Apple XLIFF format, this key won’t be exported by default.

Since our original translation file was in JSON format, the key is assigned to the Web platform. You can assign the key to additional platforms by opening the General tab in the key editor and adjusting the Platforms setting:

If you select an additional platform, like iOS, a new iOS tab will appear in the Assigned to file section, where you can pick an additional filename.

By default, keys are automatically assigned to the main-%LANG_ISO%.json filename. However, keys created manually in the key editor are not assigned to any filename, so you’ll need to select a file from the dropdown to assign it.

You have several options:

Don't assign to file on platform — the key won’t be assigned to any filename.
New file — when selected, you’ll be prompted to enter a new filename upon saving.
Existing file — choose any existing file to assign the key to.

Filenames and file exporting

Filenames play a crucial role when exporting translations from Lokalise.

Let’s assume you’ve assigned the welcome key to the iOS platform and linked it to the %LANG_ISO%.xliff filename. Additionally, you’ve created a new demo key that isn’t assigned to any filename.

View image

To export, go to the Download page and select JSON from the File format dropdown (since JSON was the original format of your translation files).

Then, expand the File structure section.

This is where you can choose how exactly your translations should be organized.

One file per language — this option ignores previously assigned filenames. Translations are stored in separate files based on language, using a pattern provided in the text input. For example, if you use locale/%LANG_ISO%.%FORMAT%, the English translations will be in locale/en.json, and the Latvian translations in locale/lv.json.
So, in the example above, all English translations will be stored inside the locale/en.json file whereas all Latvian translations will go into the locale/lv.json file.
Multiple files per language — this option uses the filenames you previously assigned to group your translation keys. You can add a directory prefix with a placeholder, or leave it blank to avoid extra directories. Since we chose the JSON format (which belongs to the Web platform), Lokalise will use the Web platform filenames. The download bundle will include two files (en/main-en.json and lv/main-lv.json), containing the welcome and how_are_you keys. If you choose the Apple XLIFF format, the how_are_you key won’t be exported (as it’s only on the Web platform), but the welcome key will be, since it’s on both Web and iOS platforms. The files will be named en/en.xliff and lv/lv.xliff.

But what happens to the demo key when Multiple files per language is selected? Since it’s not assigned to any filename, will Lokalise ignore it? No, the demo key will still be exported and placed in a file called no_filename.json (the extension depends on the chosen output format).

If you prefer not to have the demo key in no_filename, you can go back to the project editor and assign it to a specific filename.

Uploading and downloading different file structure patterns

In this section, we’ll explore how to upload and download files based on different file and folder structures. Some examples use the Lokalise CLI tool, so you may want to install it first.

Example 1. Single file per language

Suppose you have two translation files:

locale/en.json
locale/lv.json

You can upload these files using the graphical UI or the CLI:

# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file upload \
  --file "locale/en.json" \
  --lang-iso en

# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file upload \
  --file "locale/lv.json" \
  --lang-iso lv

To keep one file per language when exporting, enable the corresponding option in the graphical UI or use the CLI:

If you are using the CLI, run the following command:

# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file download \
  --format json \
  --bundle-structure "locale/%LANG_ISO%.json" \
  --original-filenames=false \
  --unzip-to .

Example 2. Language code is part of the folder name

This pattern is common for Android and iOS. For example:

values/strings.xml
values-lv/strings.xml

Upload these files using the graphical UI or the CLI:

# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file upload \
  --file "values/strings.xml" \
  --lang-iso en


# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file upload \
  --file "values-lv/strings.xml" \
  --lang-iso lv

To download, use the graphical UI or the CLI:

# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file download \
  --format xml \
  --bundle-structure "values-%LANG_ISO%/strings.xml" \
  --original-filenames=false \
  --unzip-to .

Note: If it’s a base language, the system will omit the -%LANG_ISO% part as required by Android.

Example 3. Multiple files per language in a folder

Suppose you have multiple translation files stored in folders named after the language ISO codes:

en.lproj/Localizable.strings
en.lproj/Extra.strings
lv.lproj/Localizable.strings
lv.lproj/Extra.strings

Upload these files using the graphical UI or the CLI:

# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file upload \
  --file "en.lproj/\*.strings" \
  --lang-iso en


# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file upload \
  --file "lv.lproj/\*.strings" \
  --lang-iso lv

Note, we've escaped * on Linux/Mac.

Download them using the graphical UI or the CLI:

# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file download \
  --format strings \
  --directory-prefix "%LANG_ISO%.lproj" \
  --original-filenames=true \
  --unzip-to .

We've added --directory-prefix along with --original-filenames parameters here.

Example 4. Multiple folders, language code is a part of the filename or folder

For complex scenarios with multiple translation files in different locations, where the path includes the language ISO code:

moduleFirst/src/main/res/values-en/strings.xml
moduleFirst/src/main/res/values-lv/strings.xml
moduleSecond/src/main/res/values-en/strings.xml
moduleSecond/src/main/res/values-lv/strings.xml

Upload these files using the CLI with the --include-path option:

# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file upload \
  --file "ModuleFirst/src/main/res/values-en/strings.xml,\
          ModuleSecond/src/main/res/values-en/strings.xml" \
  --include-path=true \
  --lang-iso en


# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file upload \
  --file "ModuleFirst/src/main/res/values-lv/strings.xml,\
          ModuleSecond/src/main/res/values-lv/strings.xml" \
  --include-path=true \
  --lang-iso lv

Alternatively, you can drag and drop your translation directories in the graphical editor, then manually adjust the filenames to include the full directory prefix.

To download, use the graphical UI or the CLI:

# lokalise2 \
  --token <token> \
  --project-id <project_id> \
  file download \
  --format xml \
  --original-filenames=true \
  --directory-prefix ""
  --unzip-to .

Note: The empty --directory-prefix parameter prevents the creation of language folders, as they are part of the filename.

Different language codes for different platforms

Since Lokalise allows you to store multiple platform files in the same project, it’s often necessary to use different language codes depending on the format you are exporting. To manage this, you’ll need to adjust the language codes manually in the Web UI on the Download page. After making your adjustments, click Build to save the settings.

When using the CLI tool, Lokalise will apply the last saved settings for the specified file format, ensuring that the correct language codes are used during export.