Documentation section

Upload Reference

Learn about how to configure what files to upload to the Localazy platform.

The upload section defines how to collect files that you want to upload to the Localazy platform for localization and what metadata to include. It also defines how to process uploaded data.

If you need to upload existing translations along with your source language, be sure to learn more about it to prevent future issues.

Upload configuration 🔗

You can configure many parameters such as product flavors, build types, modules and libraries. It allows you to fit Localazy for your project. You don’t need to change your project to fit the localization solution.

However, as CLI comes with sensible defaults, the most common case is to use upload in its simplest form.

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

  "upload": {
    "type": "json",
    "files": "path/*/file.json"
  }

}

The full configuration of the upload section is:

{

  "upload": {
    "skipFailedAutodetection": true,
    "deprecate": "file",
    "importAsNew": false,
    "forceCurrent": false,
    "allowDuplicateKeys": true,
    "filterSource": true,
    "appVersion": 0,
    "keySeparator": ".",
    "includeKeys": ["REGEX:key_.*"],
    "excludeKeys": ["REGEX:private_.*"],   
    "type": "json",
    "features": ["multilingual", "..."],
    "folder": "",
    "files": [
      // ...see Files configuration below ...
    ]   
  } 

}
Field Default Description
skipFailedAutodetection true When set to true files that use auto-detection are skipped if the auto-detection is not possible. When set to false an exception is raised.
deprecate no Tells the server to deprecate any key missing in this upload batch. Deprecated keys are still available but are not visible to translators. With value file, only keys missing in touched files are deprecated. With value project, all keys missing in this upload batch across whole project are deprecated. Available from v1.6.0
deprecateMissing false Tells the server to deprecate any key missing in this upload batch. Deprecated keys are still available but are not visible to translators. Deprecated - please use deprecate=project instead
importAsNew false Tells the server to import new phrases as unverified. Unverified phrases need to go through the review process. This option allows you to check translations using our unique review process if you are not sure of their quality. This option doesn’t apply to the source language.
forceCurrent false Tells the server to promote changes in translated files as approved and current translations for phrases that are already translated. If set to false, such changes go to the review process.
allowDuplicateKeys true By default, you can have phrases with the same key in different files. For specific situations like using libraries and string overriding, it’s necessary to disable this option. More on this topic in Modules, libraries, product flavors. Under normal circumstances, you should NOT set this option to false!
filterSource true When set to true, strings that are the same as in the source language are not imported. This is important for platforms like iOS where localizable files contain the source phrase where the translation is not available. This option doesn’t apply to the source language.
appVersion 0 Tells the server the version of the app in which the phrases where deprecated. It only makes sense with deprecateMissing switched to true. It allows for automatic versioning of deprecated phrases. This option can be provided on the command-line with -v option.
keySeparator . The separator used for building structured keys for includeKeys and excludeKeys. See excluding string keys for more details.
includeKeys [] A list of rules for determining keys to include. See excluding string keys for more details.
excludeKeys [] A list of rules for determining keys to exclude. See excluding string keys for more details.
type The type of files you are about to upload. The list of supported file formats is below. You can also defined the type separately for each of files. See Files configuration below.
features [] The list of features (eg. how to parse plurals) to enable for the given type. See the list of supported file formats below for more information.
folder . The base folder all operations are relative to. It can be relative or absolute path.
files Defines how to collect files for uploading and what parameters to upload along with them. See Files configuration below.

Files configuration 🔗

The files contains a list of rules for collecting files for upload.

You can include files by their exact path or by using standard path wildcards ? (single character), * (anything except path separator), ** (anything including path separators).

You can control files that you want to upload with exclusion rules and conditions.

Single file rule 🔗

This variant is useful mainly for uploading the source language only.

{
  "upload": {
    // ...other configuration...
    "files": "/path/to/file_en.json" 
  }
}

When the files is specified as string instead of array, CLI uses the string for pattern and inherit default values for all other fields.

Full rule configuration 🔗

The full configuration of files rule:

{
  "upload": {
    // ... other configuration ...

    "files": {
      "group": "all-langs", 
      "pattern": "/path/to/*_en.json",
      "excludes": [ 
        "**/private_*"
      ],
      "type": "json",
      "features": ["multilingual"],
      "conditions": [ ... ],
      "lang": "${lang}",
      "buildType": "debug",
      "productFlavors": "0:gp 1:free",
      "module": "...",
      "library": "...",
      "path": "...",
      "file": "...",
    }
  
  }
}
Field Default Description
group Allows to filter rules using groups. See groups for more information.
pattern The pattern to use for collecting files. Standard path wildcards ? (single character), * (anything except path separator), ** (anything including path separators) are supported.
excludes [] The list of patterns used for excluding files. Standard path wildcards ? (single character), * (anything except path separator), ** (anything including path separators) are supported.
type The type of files you are about to upload. The list of supported file formats is below. Setting this field overrides value set for the whole upload section.
features [] The list of features (eg. how to parse plurals) to enable for the given type. See the list of supported file formats below for more information. Setting this field overrides value set for the whole upload section.
conditions Allows for more complex inclusion/exclusion of files. See Conditions for more details.
file ${autodetectFileWithFallback} The file name to be used for upload. It’s a good practise to clean file names. See The important rule below.
path `` The path to be used for upload. It’s a good practise to clean paths. See The important rule below.
lang inherited The language of the file being uploaded (format: ll-Scrp-RR). Special default value inherited means the project’s base language.
buildType The custom build type for the file. See Modules, libraries, flavors for more details.
productFlavors The custom product flavors for the file. See Modules, libraries, flavors for more details.
module The module the file belongs to. See Modules, libraries, flavors for more details.
library The library the file belongs to. See Modules, libraries, flavors for more details.

Multiple rules 🔗

You can use array for files and combine single file rules with the full configuration rules:

{
  "upload": {
    // ...other configuration...

    "files": [
      "/path1/to/file_en.json",
      "/path2/to/file_en.json",
      {
        "type": "android",
        "pattern": "/src/main/values/string.xml"
      }
    ]

  }
}

How the upload works 🔗

  • The target directory is scanned for all files that match pattern.
  • Files that match any of the rules in excludes are skipped.
  • Files with conditions evaluated to false are skipped.
  • For each of files, all parameters are resolved - variables and transformations are extremely important here to provide the correct data.
  • The verification process is initiated asking the server for verifying types, features, etc.
  • If the verification passes, the files are uploaded to the server in a single batch.
  • Files are processed by our server asynchronously and you are informed using the notifications on the Localazy platform.

Supported file formats 🔗

We believe that you shouldn’t change your project to fit the localization solution.

For this reason, we have advanced support for formats like JSON that can handle different plural types, arrays, structured JSONs, multilingual JSONs, Mozilla i18n, etc. You can easily configure the features you need.

Name Type Description
Android android Full support for Android XML including array-lists and plurals.
iOS / macOS ios-strings
ios-stringsdict
ios-plist
xliff
Full support including extended support for arrays and plurals.
Flutter ARB arb Full support for Flutter ARB format including arrays and plurals.
JSON json Plain JSON, structured JSON, Mozilla i18n, RequireJS, etc.
JavaScript js Support for JavaScript files including arrays, plurals, etc.
XLIFF 1.2 xliff XLIFF 1.2 with a support for plurals and arrays.
XLIFF 2.0 xliff XLIFF 2.0 with a support for plurals and arrays.
PO po
pot
PO files with a support for plurals.
YAML yaml YAML with a support for plurals, arrays and Ruby on Rails.
RESX resx RESX with a custom support for plurals and arrays.
JSON5 json5 Support for JSON5 - plain, structured, arrays, plurals, etc.
HJSON hjson Support for HJSON - plain, structured, arrays, plurals, etc.
Java Properties properties Java Properties with a custom support for plurals and arrays.
INI ini INI files with support for different encodings, plurals and arrays.
PHP php Array-based PHP files with support for Laravel format.
Qt TS qt-ts Qt Linquist TS format with many different parsing options.
TOML toml TOML format with a support for plurals and arrays.
NEON neon Neon (Nette Object Notation) with a support for plurals and arrays.
CSV/TSV csv Configurable CSV/TSV with a support for plurals and arrays.
Microsoft Excel excel Microsoft Excel XLS/XLSX files with a support for plurals and arrays.
OpenOffice ODS ods OpenOffice/LibreOffice Spreadsheet files with a support for plurals and arrays.
SRT Subtitles srt SubRip SRT subtitle files.
Plain Texts text Single text files - App Store description, Play Store description, README, documentation, etc.

The important rule 🔗

You shouldn’t just upload files as they are. Don’t do it! It’s important to upload files correctly (eg. remove language from file’s name and path) as it helps you to keep things nicely sorted and prevent future problems.

This rule is extremely important if you want to upload existing translations along with the source language. Learn more about how to do it.

Test before uploading 🔗

Run the Localazy CLI with parameter -s to output the list of files along with their parameters before you upload data to the Localazy platform.

This way, you are sure that everything is uploaded correctly.

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