Import & Export

Overview

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.

What You Can Choose

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 Archive Naming

ZIP files are named with:

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

Example:

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

Content Layouts

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.json
src/common/messages.fr.json
acme/fr/messages.json

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: Matricule

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.json
src/common/messages.fr.json
vanilla/fr/src/common/messages.json
capgemini/fr/src/common/messages.json
src/common/messages.capgemini.fr.json

Variants and Tenants

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

Structure Templates

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}}"
          }
        }
      }
    }
  }
}

Template Context

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[]

Metadata

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.*.

REST API Examples

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

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

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

• 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

Importing

Glossary Import/Export

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[]

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

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