Uploading existing translations is a bit tricky, but don’t worry it’s easy to do it correctly and there are auto-detection and validation features to assist you. In fact, our sensible defaults are great for majority of situations.

Specify the language! 🔗

The most important thing when uploading existing translations is to specify the language of the file.

You can use auto-detection (read more below) or obtain language from the path or filename using transformations.

{
  // ... other parts omitted for brevity ... 

  "upload": {
    "files": {
      "pattern": "src/resources/localization/strings_*.json",
      "lang": "${autodetectLang}"
    } 
  }
}

For usual situations, this is enough!

Separate the source language and translations 🔗

You should upload existing translations only once as uploading them each time could interferre with the work of your translators and contributors. It’s handy to use groups for separating upload of the source language and other translations.

When you make changes to your translations, you should change and upload the source language only and manage the rest with the Localazy platform.

The example code below defines two groups. The default one for uploading the source strings_en.json and the second one named existing for uploading everything except the source language.

Invoke localazy upload existing to upload all translations only once and later use localazy upload to upload changes to the source language.

{
  // ... other parts omitted for brevity ... 

  "upload": {

    "files": [
      {
        "pattern": "src/resources/localization/strings_en.json",
        "lang": "inherited"
      },
      {
        "group": "existing",
        "pattern": "src/resources/localization/strings_*.json",
        "excludes": ["src/resources/localization/strings_en.json"],
        "lang": "${autodetectLang}"
      }   
    ]

  }
}

The problem with different filenames 🔗

With Localazy, you can manage many files with the same keys. Therefore, the key is not the only differentiator. You must ensure that path, filename and key is the same to link translations correctly. You can imagine it as if the full key to the strings would be consisted of path, file and actual key.

Typically, translations are placed in folders or files with different names (usually containing the locale code).

Imagine that you have translations stored like this:

src/resources/localization/strings_en.json  // your source language
src/resources/localization/strings_cs.json
src/resources/localization/strings_fr.json

If you would upload them with their original paths and filenames, you end up with strings_cs.json and strings_fr.json not being imported at all as they don’t have the source language. Why? Because the path is the same for all files (src/resources/localization) but filenames are different (strings_en.json, strings_cs.json, strings_fr.json).

And the simple solution 🔗

You can solve the example issue above easily by forcing the same filename strings.json for all files.

By default, Localazy tries to do that automatically and takes file from ${autodetectFileWithFallback} that, if possible, remove the locale code and clear the filename. You can do it manually for complex situations or if the auto-detection fails.

{
  // ... other parts omitted for brevity ... 

  "upload": {
    "files": {
      "pattern": "src/resources/localization/strings_*.json",
      "lang": "${autodetectLang}",
      "file": "strings.json"
    } 
  },

  "download": {
    "files": "src/resources/localization/strings_${lang}.json"  
  }

}

The important rule 🔗

Take time to upload your files correctly (eg. remove language from the file’s name and path) as it helps you to keep things nicely sorted and prevent future problems.

If you don’t do and decide to change paths, files and other parameters later, you can hit the wall as the phrases may be uploaded in separated namespaces. In Localazy, we have mechanisms such as InTM to assist you with moving namespaces, but it’s always better to avoid it if possible.

Always run the CLI in simulation mode with localazy upload -s to test your data before uploading them.

Auto-detecting paths, files and languages 🔗

For each of files collected based on patterns in the upload section, the auto-detection is run automatically.

The algorithm tries to detect the locale (language, region and script) from the both file and path and clean the path and file accordingly.

Based on the results of the auto-detection algorithms, extra variables are available:

By default, if the auto-detection fails, and the file uses any of the variables above (except for ${autodetectFileWithFallback}), it’s skipped. You can configure the auto-detection to do not skip files for which it fails using skipFailedAutodetection in the upload section.

Always run the CLI in simulation mode with localazy upload -s to see the results of the auto-detection prior to uploading your files!

Add existing translations to the uploaded strings 🔗

If you uploaded your source language before and want to add also existing translations, just be sure to use the same configuration (file, path, etc.) and upload them. Localazy takes care about the rest.

Tip: You can list all files for the given app by running localazy list with the minimal configuration:

{
  "writeKey": "your-apps-write-key", 
  "readKey": "your-apps-read-key"
}

It will help you to upload existing translations correctly.

Modules, libraries, product flavors, … 🔗

Localazy comes with support for advanced concepts for complex projects such as modules, libraries, product flavors and build types.

When it comes to uploading existing translations, the logic is the same as for paths and files. Eg. the same key in different product flavors is like having two different keys.

Learn more information about modules, libraries, product flavors and build types.