Filenames

Learn about filenames and different approaches to file naming with CLI import/export examples.

Nick Ustinov avatar
Written by Nick Ustinov
Updated over a week ago

In this article you'll learn how to work with filenames on Lokalise.

Introduction

Lokalise operates without storing files or file templates in their original form. When you upload translation files, Lokalise parses them to extract the keys and values, which are then saved in its database. However, it does maintain a record of the original files to which these keys belong, captured in the filename attribute.

Upon downloading translations to your computer, Lokalise dynamically generates files in your chosen format. This process allows you the flexibility to either maintain the original file structure and names or to create an entirely new organization as per your requirements. Additionally, you have the option to modify the names of these files or reassign your keys to different files with ease.

Filenames and file uploading

Let's see how the filenames are going to be stored on Lokalise when you upload translation files. Suppose we 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?"
}

Proceed to the Upload page, click Select a file and choose these two files:

You can click on the filename to adjust it:

Note that Lokalise has automatically detected the en language ISO code and has replaced it with the %LANG_ISO% placeholder. As we are going to see next, this is a very convenient feature so recommend keeping this placeholder in the filename.

Click Import files and return to the project editor:

Take a look at the main-%LANG_ISO%.json text under key names: this is the filename that your keys were assigned to. As long as our initial filenames followed the same pattern and contained the language ISO codes, Lokalise was able to assign all keys to a single "universal" filename for your convenience.

Does it mean that the original filenames are lost? Of course not! As we see next, when the translations are downloaded back to your PC we'll be able to replace the %LANG_ISO% placeholder with the actual language code.

You can click on the filename under the key name to apply a filter and show only the keys that belong to the corresponding file:

Files widget

You can view all translation files that your project currently contains by opening the Files widget from the top menu:

You'll be presented with the following dialog:

We can see that our project contains two files.

  • Use the search box to search for a file by its name.

  • Click on the filename to show only the keys assigned to this file.

  • Click on the three small 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 actually supports storing additional data.

Assigning keys to filenames

You can assign or unassign existing keys to/from filenames inside the key editor. In order to open the key editor, click on the key name:

Proceed to the Advanced tab in the key editor and find the Assigned to file section:

Please note that the file assignment is performed on a per-platform basis.

As explained in the Keys and platforms article, Lokalise supports four platforms: Web, iOS, Android, Other. Each key must be assigned to at least one platform, and the platform determines whether the key will be included in the download bundle depending on the chosen output file format. For instance, if the key belongs to the Web platform and you choose to export your translations in the JSON format, this key will be included in the bundle (because JSON is a popular format for Web). If, however, you choose the Apple XLIFF format, this key won't be exported by default.

Also, as long as our initial translation file had the JSON format, the key is assigned to the Web platform. However, you can assign the key to additional platforms by opening the General tab in the key editor and adjusting the Platforms setting:

If you pick, say, and iOS platform then the Assigned to file section will contain a new iOS tab where you can pick additional filename:

So, as we already know, our key was automatically assigned to the main-%LANG_ISO%.json filename. However, keys that are created manually using the key editor are not assigned to any filename by default, so you can use this dropdown to pick a file to assign to.

You have multiple options:

  • Don't assign to file on platform — this key will not be assigned to any filename at all.

  • New file — when this option is picked and the changes are saved, you'll be prompted to enter a filename to assign to.

  • Existing file — choose any existing file to assign to.

Filenames and file exporting

Filenames are very important when translations are exported from Lokalise.

Let's suppose that we've assigned the welcome key to the iOS platform and linked it to the %LANG_ISO%.xliff filename. Also we've created a new demo key that is not assigned to any filename:

Let's proceed to the Download page and choose JSON in the File format dropdown (remember that JSON was the original format of our translation files):

Now expand the File structure section:

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

  • One file per language — if you choose this setting then Lokalise will effectively ignore all the previously assigned filenames. Your translations will be stored in separate files on a per-language basis, and these files will be named using the pattern provided in the text input. Note that this pattern can also contain directory names, for example locale/%LANG_ISO%.%FORMAT% where locale is the directory name. %LANG_ISO% is a placeholder that will be replaced with the language ISO code and the %FORMAT% is also a placeholder that will be replaced with the extension based on the chosen output format (.json in our case).
    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 — if this option is chosen, Lokalise will use the previously assigned filenames to group your translation keys. You can provide a directory prefix that should be used to further group your files, and this prefix can contain a placeholder. If you don't want to group translation files under additional directories, simply clear the text input.
    As long as we've chosen the JSON output format, and this format belongs to the Web platform, Lokalise will use the filenames that were assigned to the Web platform. It means that your download bundle will contain two files with both welcome and how_are_you translation keys. The files will be named en/main-en.json and lv/main-lv.json. However, if you choose the Apple XLIFF output format, then the how_are_you will not be exported at all as it belongs to the Web platform only. The welcome key will still be exported as it belongs to both Web and iOS platforms. Note that in this case Lokalise will use the filename that was specifically set for the iOS platform (%LANG_ISO%.xliff) therefore the export bundle will contain en/en.xliff and lv/lv.xliff files.

But what is going to happen to the demo key when the Multiple files per language option is selected? After all, we have not assigned this key to any filename. Will Lokalise ignore this key? No, it will still be exported and stored inside a file called no_filename.json (the file format will depend on the chosen output format):

Of course, you can return to the project editor and assign the demo key to any filename so that it's not stored inside the no_filename.

Uploading and downloading different file structure patterns

In this section we'll see how to perform uploading and downloading depending on your file and folder structure. Some of these examples use the Lokalise CLI tool, so you might 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 by using the graphical UI or via 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

If you'd like to keep one file per language upon exporting, you can enable the corresponding option in the graphical UI:

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 used on Android and iOS. This example is quite similar to first one:

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

You can upload these files by using the graphical UI or via 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

Downloading using the graphical UI:

Downloading using 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, we are using values-%LANG_ISO%/strings.xml here, however in the case that it is a base language, the system will omit the -%LANG_ISO%  part as required by Android.


Example 3. Multiple files per language in a folder

Now let's suppose that we have multiple translation files that should be stored in the folder named after the language ISO codes:

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

You can upload these files by using the graphical UI or via 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.

Downloading using the graphical UI:

Downloading using 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

Finally, suppose we have multiple translation files that are stored in different locations and the path contains 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

This scenario is more complex because you'll need to preserve the full directory prefix. One option is to upload your files using the CLI and provide 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

Another option is to open the graphical editor and drag'n'drop your translation directores right on the page. Then before starting the upload process adjust the filenames manually and include full directory prefix:

Downloading using the graphical UI:

Downloading using CLI:

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

Note that we are using the empty --directory-prefix  parameter here to omit creation of language folders, as they are part of the filename.

Different language codes for different platforms

As Lokalise allows storing multiple platform files in the same project it's often important to have different language codes depending on the format you are exporting. You need to adjust this manually in Web UI and the Download page. Once adjusted, click Build to save the settings. Now, when using the CLI tool, the system will apply the last saved setting for that particular file format.

Did this answer your question?