The download section defines where to store translated files.

There are a lot of variables for the download section that you can use for building the output path and file.

Single output rule #️⃣

For each of the translated files, the output path is generated using the pattern /path/${lang}/${file}.

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

  "download": {
    "files": "/path/${lang}/${file}"
  }

}

Full output configuration #️⃣

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

  "download": {
    "folder": "output/path",
    "metadataFileJson": "meta.json",
    "metadataFileJs": "meta.js",
    "metadataFileTs": "meta.ts",
    "includeSourceLang": false,
    "excludedLangs": ["cs", "de"],
    "langAliases": {
      "zh-Hant-TW": "zh-TW"
    },
    "langExpansions": {
      "de": ["de-DE", "de-CH"]
    },
    "files": {
      "group": "all",
      "conditions": [ ... ],
      "stop": true,
      "changeExtension": "json",
      "output": "path/${lang}/${file}"
    }   
  }

}

Multiple output rules #️⃣

You can use an array for files and combine single output rules with full output configurations:

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

  "download": {
    // ..
    "files": [
      "path1/${lang}/${file}",
      {
        "conditions": [ ... ],
        "stop": true,
        "output": "path2/${lang}/${file}"
      }
    ]   
  }

}

When more rules are defined, each of the translated files goes through all of them.

You can store all or some of the files in multiple locations. When using more rules, conditions and stop are useful concepts.

How download works #️⃣

• Your files are downloaded from our servers.
• Each of the files goes through all the rules in the order defined in the files section.
• Rules with conditions evaluated to false are skipped.
• When the rule is valid (conditions are evaluated to true) and stop is true, no more rules are processed.

Example with more output locations #️⃣

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

  "download": {
    // ..
    "files": [

      {
        "stop": false,
        "output": "backup/${lang}/${file}"
      },
      
      {
        "conditions": "!empty: ${scriptCode}",
        "stop": true
      },

      {
        "conditions": "!empty: ${regionCode}",
        "stop": true,
        "output": "withRegion/${langLsrUnderscore}/${file}"
      },

      "withLang/${lang}/${file}"

    ]   
  }

}

• All files are stored using backup/${lang}/${file} pattern, and the processing is not stopped and continue.
• If the locale of the given file contains script code, the processing is stopped.
• If the locale of the given file contains region code, it’s saved using withRegion/${langLsrUnderscore}/${file} pattern, and the processing is stopped.
• All other files are stored using withLang/${lang}/${file}

Missing translations #️⃣

When you generate an output file using Localazy, it will use the source language as a fallback if a translation is missing in the target language. This helps prevent missing keys that could cause crashes in some frameworks.

If you want to disable this fallback feature, you can add filter_untranslated to the features section in the upload and reupload your source language file. Note that this feature may not be available for all file formats, so check their documentation for details.

Note that in order to download a file with fallback translations, the target language must have at least one translation present. If there are no translations, the language won’t appear in the output.

Test before download #️⃣

Downloaded files overwrite any existing files. Be careful before you proceed!

Run the Localazy CLI with parameter -s to output the list of files that are about to be written before you download and store translated files.

This way, you are sure everything is stored correctly, and you are not about to mess your project.

The parameter -s switches CLI to the simulation mode - everything is processed as usual, but the actual storing is not performed.

localazy download -s

Listing files on server #️⃣

To list all files for the given project, you can run localazy list with the minimal configuration:

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