CLI: Upload Reference | Localazy Docs

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,
    "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`	none	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. With default value `none`, nothing is 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.
`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.

Upload Reference

Last updated

Read time

Article content