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 projectid
orslug
. 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
.
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. |