Skip to content

Import & Export

LokAI exports translation files as a ZIP archive that preserves your logical file structure.

An export is shaped by two independent layers:

  1. Content layout: what goes inside each file
  2. Archive path layout: where each file is placed inside the ZIP

This separation lets you keep the same translation content while changing how files are organized for a specific app, framework, or deployment flow.

When exporting from Studio or the REST API, you can choose:

  • Version
    • latest: include the most recent translation/customization state
    • validated: include only validated or published translations, and approved tenant customizations
  • Languages
    • export one, many, or all configured project languages
  • Tenant variants
    • export the vanilla version, one or more tenants, or both
  • Format
    • JSON, YAML, TOML, CSV, XLIFF, Android XML, iOS strings, ARB, RESX, Java properties, TMX, and more
  • Format options
    • metadata
    • structure template
  • Archive path pattern
    • choose how files are named and nested inside the ZIP

ZIP files are named with:

{project-slug}-{latest|validated}-{YYYY-MM-DD}.zip

Example:

marketing-site-validated-2026-04-04.zip

per_language is the default layout.

Each file contains one language only.

Example JSON payload:

{
"home.title": "Welcome",
"home.subtitle": "Start here"
}

Typical archive paths:

fr/messages.json
src/common/messages.fr.json
acme/fr/messages.json

multilingual is currently available for JSON and YAML exports only.

Each file contains all selected languages together. This is useful when the consuming application expects a single document with a root array or another custom multilingual structure.

Example YAML shape:

- name: i18n.Talent.externalId
description: Employee identifier
doNotTranslate: false
doNotCustomize: false
tags:
- talent
translations:
- language: en
text: Registration number
customizations:
- code: capgemini
text: GGID
- language: fr
text: Matricule

Archive paths are controlled with a path_template.

Supported tokens:

  • {language}
  • {variant}
  • {tenant}: alias for {variant}
  • {file}
  • {ext}

{file} always refers to the key file path without extension.

Examples:

{language}/{file}.{ext}
{file}.{language}.{ext}
{variant}/{language}/{file}.{ext}
{language}/{variant}/{file}.{ext}
{file}.{variant}.{language}.{ext}

Example output:

fr/src/common/messages.json
src/common/messages.fr.json
vanilla/fr/src/common/messages.json
capgemini/fr/src/common/messages.json
src/common/messages.capgemini.fr.json

When tenant export is enabled:

  • vanilla is the base non-customized variant
  • each tenant uses its tenant slug as the variant token

That means the following path template:

{variant}/{language}/{file}.{ext}

can produce:

vanilla/fr/messages.json
capgemini/fr/messages.json
atos/fr/messages.json

Structured exports can use a JSON template to shape the generated content.

Supported today:

  • json
  • json-nested
  • yaml
  • toml

For simple per-language exports, placeholders can map a single translation key:

{
"hero": {
"title": "{{home.hero.title}}",
"subtitle": "{{home.hero.subtitle}}"
}
}

For advanced JSON/YAML exports, templates also support:

  • loops with $for
  • aliases with $as
  • loop body with $body
  • conditionals with $if, $then, and $else

Example multilingual root-array template:

{
"$for": "keys",
"$as": "key",
"$body": {
"name": "{{key.name}}",
"description": "{{key.description}}",
"translations": {
"$for": "key.translations",
"$as": "translation",
"$body": {
"language": "{{translation.language}}",
"text": "{{translation.text}}",
"customizations": {
"$for": "translation.customizations",
"$as": "customization",
"$body": {
"code": "{{customization.code}}",
"text": "{{customization.text}}"
}
}
}
}
}
}

Templates can read from:

  • project
    • project.id
    • project.slug
  • export
    • export.format
    • export.version
    • export.contentMode
    • export.language
    • export.variant
    • export.file
    • export.ext
  • entries
    • available for per-language exports
  • keys
    • available for multilingual exports

Multilingual keys contain:

  • key-level metadata such as name, description, tags, status, doNotTranslate, doNotCustomize
  • translations[]
  • nested translation.customizations[]

include_metadata=true is currently supported for:

  • json
  • json-nested
  • yaml

When enabled in per-language exports, each key becomes:

{
"home.title": {
"value": "Welcome",
"metadata": {
"key_id": "...",
"language": "fr",
"translation_status": "validated",
"variant": "tenant",
"tenant_id": "...",
"value_source": "tenant_customization"
}
}
}

For per-language exports with a custom structure template, metadata stays available through the template context even if include_metadata is not enabled. Use entries and reference fields such as entry.metadata.file, entry.metadata.translation_status, or entry.metadata.tags.

include_metadata mainly changes the default fallback shapes. It wraps each exported key as { value, metadata } when you are not using a custom structure template.

In multilingual exports, the default fallback object includes the full key and translation metadata-rich records. If you use a custom structure template, you control which metadata fields are emitted by selecting them explicitly from key.*, translation.*, and translation.customizations.*.

Terminal window
curl -L \
-H "Authorization: Bearer <token>" \
"https://api.lokai.cloud/api/v1/workspaces/<workspace-id>/projects/<project-id>/export/bulk/json?languages=fr,de&version=validated"

Tenant-aware export with custom archive paths

Section titled “Tenant-aware export with custom archive paths”
Terminal window
curl -L \
-H "Authorization: Bearer <token>" \
"https://api.lokai.cloud/api/v1/workspaces/<workspace-id>/projects/<project-id>/export/bulk/json?languages=fr&tenant_ids=all&path_template=%7Bvariant%7D%2F%7Blanguage%7D%2F%7Bfile%7D.%7Bext%7D"
Terminal window
curl -L \
-H "Authorization: Bearer <token>" \
"https://api.lokai.cloud/api/v1/workspaces/<workspace-id>/projects/<project-id>/export/bulk/yaml?languages=en,fr,es&content_mode=multilingual"
  • multilingual content mode currently supports only JSON and YAML
  • TOML is supported for structured per-language exports, but is not a good fit for root-array multilingual documents
  • include_metadata is not yet supported on every file format
  • some formats remain intentionally unimplemented, such as PHP arrays and Excel .xlsx

Glossary data supports direct import and export in:

  • json
  • yaml
  • csv

Export endpoint:

GET /api/v1/workspaces/:workspaceId/glossary/export?format=json|yaml|csv

Import endpoint:

POST /api/v1/workspaces/:workspaceId/glossary/import
Content-Type: application/json
{
"format": "json",
"content": "{ \"entries\": [ ... ] }"
}

The import returns an operation summary:

  • created
  • updated
  • failed
  • errors[]

Each request supports up to 1,000 glossary entries and 1 MiB of UTF-8 file content, whichever limit you reach first. The HTTP body can be up to 8 MiB to accommodate JSON escaping of the content. These limits apply to REST and standalone tRPC glossary imports on every plan. tRPC batches keep the default 1 MiB body limit; send larger imports as standalone calls.

  • Bodies or content over their byte limits return 413 with PAYLOAD_TOO_LARGE.
  • More than 1,000 entries returns 400 BAD_REQUEST before any writes.
  • JSON and YAML count elements of entries. CSV groups rows by translation mode and case-insensitive title; several translation rows can belong to one entry.

Split larger files into several requests. Keep each request within both limits, and keep all CSV translation rows for one entry together. Measure content as UTF-8 bytes, not JavaScript string length.

Imports are best-effort across entries. Writes run in transactions of up to 100 entries. Each entry’s metadata, supplied translations and history succeed or roll back together. A failed translation or permission check leaves that entry unchanged while other entries can succeed. A failed batch commit rolls back that batch; completed batches remain saved.

The REST response is 201 with the operation summary even when failed is greater than zero. Resolve the reported errors, then retry only failed entries. Re-importing successful entries updates them again and can affect history. Matching uses translation mode and case-insensitive title. Leading and trailing whitespace, including tabs, newlines and non-breaking spaces, is ignored; internal whitespace remains significant. Omitted fields still use the import format’s existing defaults.

Key bulk creation has a separate limit of 100 keys within the default 1 MiB HTTP body. Keys are attempted independently, successful keys remain saved after partial failure, and no transaction covers the whole request. Retry only failed keys to avoid duplicate-name errors.

Today, LokAI can ingest structured translation files and reconcile them with existing keys, but export capabilities are ahead of import in terms of customization and documentation.

See the GitHub Integration guide for automating import and export inside your delivery pipeline.