Import

Learn how to import content to Localazy.

About Imports 🔗

Each imported key must be stored inside a file. In Localazy, a file is a set of keys and their translations.

You can configure your string keys to be backed by some translation file format using the content.type property during import. This allows you to download the content later using our CLI or CDN.

If not specified, an internal API format will be used and the files won’t be available through CLI and CDN.

To get a list of all available file formats, check the /import/formats endpoint.

Import content to a project 🔗

[POST] /projects/{projectId}/import
Description Value
Accessible with project token true
Accessible with organization token true
Need write permission true
Available from role owner
API level normal

Import any supported file format to the selected project including the translations.

Sample Request 🔗

curl --request POST \
  --url 'https://api.localazy.com/projects/{projectId}/import' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "files": [
    {
      "name": "file.json",
      "content": {
      "type": "json",
        "en": {
          "hello_world": "Hello World!"
        },
        "fr": {
          "hello_world": "Salut tout le monde!"
        }
      }
    }
  ]
}'

Request Object

{
  "importAsNew": false,
  "forceCurrent": false,
  "filterSource": true,
  "files": [
    {
      "name": "file.ext",
      "path": "path/to/file",
      "module": "",
      "library": "",
      "buildType": "",
      "productFlavors": [],
      "content": {
        "type": "json",
        "plural": "plural_postfix_br",
        "array": "array",
        "keyTransformer": "dot",
        "params": {
          "paramKey": "Param Value"
        },
        "features": [
          "filter_untranslated"
        ],
        "en": {
          "key": "text"
        },
        "cs": {
          "key": "text"
        }
      }
    }
  ]
}
Field Default Description
importAsNew false Import all translations to go through the review process. Useful when you are unsure about their quality and want to do an extra check.
forceCurrent false Import all translations and set them as the current version. By default, Localazy doesn’t overwrite existing current translations and lets you decide through the review process.
filterSource true Do not import translations that are the same as the source language content.
files [] The structure of files and strings to be imported. See “File Object” below.

File Object

Field Default Description
name required The file name is required.
path optional The path to the file without the file name.
module optional Optional module specification.
buildType optional Optional build type.
productFlavors optional Optional product flavors.
content {} Content of the file - strings to be imported. See “Content Object” below.

Each file is defined by unique combination of name, path, module, buildType and productFlavors. All these parameters are available to you for creating a custom file structure. However, the only required parameter is name.

The other parameters are useful when dealing with more complex structures where file and path are not enough to describe the situation - e.g., when overriding strings based on the current module or set of product flavors.

Content Object

Field Default Description
type api Name of the file format to be used to publish strings. See /import/formats for all options.
plural - Plural type to be used for encoding plurals in the output file. Available options depend on the type. See /import/formats below.
array - Defines how to encode string arrays. Available options depend on the type. See /import/formats below.
keyTransformer - Defines how to transform structured keys for formats into plain string ones for a format that doesn’t support structured keys. Available options depend on the type. See /import/formats below.
params {} Key-value map of additional parameters that may be necessary for array, plural and keyTransformer. See /import/formats below.
features [] List of additional features for the given type. Available options depend on the type. See Localazy CLI documentation for available formats and their features.
en, cs, pl-PL, … {} Strings in the given language to be imported. See “Language Object” below.

Language Object

The content can consist of three different types of items - single strings, plurals, and string arrays. Also, there can be optional metadata.

Depending on the file type, plurals or string arrays can be filtered out if not supported.

Nested keys are supported. Some file types don’t support nested keys, and in such a situation, keyTransformer will be used to flatten keys, e.g., to level1.level2.level3.my_key.

Single strings

{
  "files": [
    {
      "name": "my_file",
      "content": {
        "en": {
          "hello_world": "Hello World!"
        }
      }
    }
  ]
}

String arrays

{
  "files": [
    {
      "name": "my_file",
      "content": {
        "en": {
          "difficulty": [
            "Easy",
            "Medium",
            "Hard"
          ]
        }
      }
    }
  ]
}

Plurals

{
  "files": [
    {
      "name": "my_file",
      "content": {
        "en": {
          "item_list": {
            "@one": "You have 1 item.",
            "@other": "You have %d items."
          }
        }
      }
    }
  ]
}

Allowed plural forms are @zero, @one, @two, @few, @many and @other. The structure is not parsed as the plural string but as nested keys if any other key appears.

Nested keys

{
  "files": [
    {
      "name": "my_file",
      "content": {
        "en": {
          "level1": {
            "level2": {
              "level3": {
                "hello_world": "Hello World!"
              }
            }
          }
        }
      }
    }
  ]
}

Metadata

At the moment, metadata can only specify an optional contextual comment for the translator. More options are coming soon.

The metadata must be on the same level in the structure.

{
  "files": [
    {
      "name": "my_file",
      "content": {
        "en": {
          "level1": {
            "level2": {
              "hello_world": "Hello World!",
              "@meta:hello_world": {
                "comment": "Please keep the exclamation mark."
              }
            }
          }
        }
      }
    }
  ]
}

Sample Response 🔗

{
  "result": "_a8451629914916913130"
}
Field Description
result ID of the import batch

Returned id will be used to fetch detailed import reports in the future.

List available file types 🔗

[GET] /import/formats
Description Value
Accessible with project token true
Accessible with organization token true
Need write permission false
Available from role translator
API level normal

Returns a list of available file types for importing strings, including their parameters.

Sample Request 🔗

curl --request GET \
  --url https://api.localazy.com/import/formats \
  --header 'Authorization: Bearer {{token}}'

Sample Response 🔗

[
  {
    "type": "android",
    "name": "Android XML",
    "supportStrings": true,
    "supportPlurals": true,
    "supportArrays": true,
    "supportStructuredKeys": false
  },
  {
    "type": "json",
    "name": "JSON",
    "supportStrings": true,
    "supportPlurals": true,
    "supportArrays": true,
    "supportStructuredKeys": true,
    "plurals": [
      {
        "type": "plural_postfix_br",
        "name": "Output plurals as keys suffixed by [pluralForm]",
        "isDefault": true
      },
      {
        "type": "plural_icu",
        "name": "Output plurals in ICU message format",
        "isDefault": false,
        "requiredParams": [
          {
            "type": "plural_variable",
            "description": "Variable name for the ICU message format"
          }
        ]
      },
      {
        "type": "plural_array",
        "name": "Output plurals as array of objects",
        "isDefault": false,
        "requiredParams": [
          {
            "type": "plural_type",
            "description": "Key for the plural form."
          },
          {
            "type": "plural_content",
            "description": "Key for the textual content."
          }
        ]
      }
    ],
    "arrays": [
      {
        "type": "array",
        "name": "Output string-array as array",
        "isDefault": true
      },
      {
        "type": "array_br",
        "name": "Output string-array as keys suffixed by [index]",
        "isDefault": false
      }
    ],
    "keyTransformers": [
      {
        "type": "none",
        "name": "Don't flatten structured keys",
        "isDefault": true
      },
      {
        "type": "dot",
        "name": "Flatten structured keys with '.'",
        "isDefault": false
      },
      {
        "type": "underscore",
        "name": "Flatten structured keys with '_'",
        "isDefault": false
      },
      {
        "type": "dash",
        "name": "Flatten structured keys with '-'",
        "isDefault": false
      },
      {
        "type": "double_dot",
        "name": "Flatten structured keys with ':'",
        "isDefault": false
      }
    ]
  }
]

Response Object

Field Description
type Type of the file that can be used in content.type.
name Name of the type.
supportStrings Indicates whether the type supports plain strings.
supportPlurals Indicates whether the type supports plurals.
supportArrays Indicates whether the type supports string arrays.
supportStructuredKeys Indicates whether the type supports structured/nested keys.
plurals The list of available types for encoding plurals. Some of the types have requiredParams that must be provided.
arrays The list of available types for encoding string arrays. Some of the types have requiredParams that must be provided.
keyTransformers The list of available methods for converting structured/nested keys to plain ones.