API: Import | Localazy Docs

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 stored in some translation file format using the content.type property during import. This allows you to download the content later in the preferred format.

If type is not specified, an internal API format will be used and the file downoad won’t be available.

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.

Params

{projectId} - Your project id or slug. Use the value from projects endpoint

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,
  "forceSource" : false,
  "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.
`forceSource`	`false`	Overwrite the source language even if there are some changes in Localazy. Useful for workflows where source of truth is outside the platform.
`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.

To add or edit and existing key, you only need to include the target keys in the payload. You don’t need to always upload the whole file’s content to make a modification. The other keys in a file will remain untouched.

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 and character limit. 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.",
                 "limit": 30
              }
            }
          }
        }
      }
    }
  ]
}

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.

Import

Last updated

Read time

Article content

Related articles

Import

About Imports #️⃣

Import content to a project #️⃣

Sample Request #️⃣

Sample Response #️⃣

List available file types #️⃣

Sample Request #️⃣

Sample Response #️⃣

Was this article helpful?

Related articles