Import & Export
Overview
Section titled “Overview”LokAI exports translation files as a ZIP archive that preserves your logical file structure.
An export is shaped by two independent layers:
- Content layout: what goes inside each file
- 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.
What You Can Choose
Section titled “What You Can Choose”When exporting from Studio or the REST API, you can choose:
- Version
latest: include the most recent translation/customization statevalidated: 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 Archive Naming
Section titled “ZIP Archive Naming”ZIP files are named with:
{project-slug}-{latest|validated}-{YYYY-MM-DD}.zipExample:
marketing-site-validated-2026-04-04.zipContent Layouts
Section titled “Content Layouts”Per-Language
Section titled “Per-Language”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.jsonsrc/common/messages.fr.jsonacme/fr/messages.jsonMultilingual
Section titled “Multilingual”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: MatriculeArchive Path Templates
Section titled “Archive Path Templates”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.jsonsrc/common/messages.fr.jsonvanilla/fr/src/common/messages.jsoncapgemini/fr/src/common/messages.jsonsrc/common/messages.capgemini.fr.jsonVariants and Tenants
Section titled “Variants and Tenants”When tenant export is enabled:
vanillais 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.jsoncapgemini/fr/messages.jsonatos/fr/messages.jsonStructure Templates
Section titled “Structure Templates”Structured exports can use a JSON template to shape the generated content.
Supported today:
jsonjson-nestedyamltoml
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}}" } } } } }}Template Context
Section titled “Template Context”Templates can read from:
projectproject.idproject.slug
exportexport.formatexport.versionexport.contentModeexport.languageexport.variantexport.fileexport.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[]
Metadata
Section titled “Metadata”include_metadata=true is currently supported for:
jsonjson-nestedyaml
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.*.
REST API Examples
Section titled “REST API Examples”Per-Language JSON export
Section titled “Per-Language JSON export”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”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"Multilingual YAML export
Section titled “Multilingual YAML export”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"Current Limitations
Section titled “Current Limitations”multilingualcontent 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_metadatais not yet supported on every file format- some formats remain intentionally unimplemented, such as PHP arrays and Excel
.xlsx
Importing
Section titled “Importing”Glossary Import/Export
Section titled “Glossary Import/Export”Glossary data supports direct import and export in:
jsonyamlcsv
Export endpoint:
GET /api/v1/workspaces/:workspaceId/glossary/export?format=json|yaml|csvImport endpoint:
POST /api/v1/workspaces/:workspaceId/glossary/importContent-Type: application/json{ "format": "json", "content": "{ \"entries\": [ ... ] }"}The import returns an operation summary:
createdupdatedfailederrors[]
Glossary import limits and retries
Section titled “Glossary import limits and retries”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.
CI/CD Integration
Section titled “CI/CD Integration”See the GitHub Integration guide for automating import and export inside your delivery pipeline.