Files

Endpoints for working with Localazy files.

About Files ๐Ÿ”—

In Localazy, a file is a collection of keys and their translations in all languages. Each key that is imported must be stored within a file.

Additionally, one file in Localazy can represent multiple discrete files on the filesystem. For example, the file localization.json in Localazy can be stored as en.json, cs.json, and de.json on the filesystem, depending on the language.

Complex Files ๐Ÿ”—

Localazy has a complex mechanism for overlaying and mixing files that enables advanced features like Android product flavors and dynamic app modules. While this mechanism is not typically required, it is necessary for the Android and iOS SDKs. However, it may result in limitations when working with certain files within the project.

List files in project ๐Ÿ”—

[GET] /projects/{projectId}/files
Description Value
Accessible with project token true
Accessible with organization token true
Need write permission false
Available from role translator
API level normal

Returns list of files in the project with all available parameters.

Params

Sample Request ๐Ÿ”—

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

Sample Response ๐Ÿ”—

[
  {
    "id": "_a58944132124478",
    "type": "api",
    "name": "file.json",
    "path": "path/to/file",
    "module": "module",
    "productFlavors": [
      "free",
      "google"
    ],
    "buildType": "debug"
  }
]

Response Object:

Field Required Description
id required Unique identifier of the file.
type required Type of the file; please refer to file formats. Value complex is used for complex files described above.
name required Name of the file.
path optional Stored path to the file. Optional and only available if provided.
module optional The module the file belongs to. Optional and only available if provided.
productFlavors optional A list of associated product flavours. Optional and only available if provided.
buildType optional A build type the file is associated with. Optional and only available if provided.

List file content ๐Ÿ”—

[GET] /projects/{projectId}/files/{fileId}/keys/{lang}
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 keys and their translations in language {lang} from file {fileId}.

Locale code {lang} must be in the format: ll-Scrp-RR.

Query Parameters ๐Ÿ”—

Parameter Description
deprecated=true Include also deprecated keys.
limit=1000 Number of keys to be returned in a single call (max 1000). Default 1000.
next=pageId Return next page. Used for paging large data.
extra_info=true Return additional information about keys including hidden,limit,depecated and comment attributes.
no_content=true Do not return the actual content/translation of the key.

Sample Request ๐Ÿ”—

curl --request GET \
  --url https://api.localazy.com/projects/{projectId}/files/{fileId}/keys/{lang} \
  --header 'Authorization: Bearer {{token}}'

Sample Response ๐Ÿ”—

{
  "keys": [
    {
      "id": "_a8503372675164909925",
      "key": [
        "nested",
        "key",
        "is",
        "supported"
      ],
      "value": "Single string value",
      "vid": -8476700603785392875,
      "hidden": false,
      "deprecated": -1,
      "limit": 60,
      "comment": "Comment for translator"      
    },
    {
      "id": "_a8503372675164909931",
      "key": [
        "plural_key"
      ],
      "value": {
        "@one": "There is only one item.",
        "@other": "There are %d items."
      },
      "vid": -8476700603785392875
    },
    {
      "id": "_a8503372675164909934",
      "key": [
        "string_list"
      ],
      "value": [
        "Easy",
        "Medium",
        "Hard"
      ],
      "vid": -8476700603785392875
    }
  ],
  "next": "aA89XITzNpwL"
}

Response Object

Field Required Description
keys required Array of keys contained in the file in given language. See โ€œKey Objectโ€ below.
next optional Next is the paging key. The field is not contained if there are no more pages.

Key Object

Field Required Description
id required Unique Id of the key in Localazy.
key required Aray of key components. For nested keys it contains the separate levels. For simple string keys it contains just one item.
value required Value represents the translation. It can be either string, array or object for plurals.
hidden optional Whether the string is hidden from translation interface. (enabled by extra_info param)
limit optional Translation length limit for this key. (enabled by extra_info param)
deprecated optional Whether the string is deprecated. (enabled by extra_info param)
comment optional Translation note for context. (enabled by extra_info param)
vid required Unique identifier of the current version of the translation. It can be used to determine whether the translation has changed from the last time. Useful for two-way synchronization.

Download file ๐Ÿ”—

[GET] /projects/{projectId}/files/{fileId}/download/{lang}

Download the selected file {fileId} in a language {lang}.

Sample Request ๐Ÿ”—

curl --request GET \
  --url https://api.localazy.com/projects/{projectId}/files/{fileId}/download/{lang} \
  --header 'Authorization: Bearer {{token}}'

Response ๐Ÿ”—

The endpoint returns the raw file contents without any additional metadata. Proper Content-Type and Content-Disposition headers are present.

Error Response ๐Ÿ”—

When no type parameter is specified during import, the file wonโ€™t be available for download.

{
    "success": false,
    "code": 400,
    "error":  "file_not_exists"
  }