Config File Reference
The lokai.config.yaml file configures the LokAI CLI for your project, defining your workspace, project, locale directories, and sync behaviour.
File Location
Section titled “File Location”Place lokai.config.yaml at the root of your repository (alongside your package.json or equivalent).
Full Schema
Section titled “Full Schema”version: 1
workspace: your-workspace-slugproject: your-project-slug
apiUrl: https://api.lokai.cloud # optional — defaults to the LokAI cloud API
localesDir: ./locales # path to your local translation files
format: json # json | yaml | po | xliff
mainLanguages: - en
targetLanguages: - fr - de - es - ja - zh
pullOptions: includeDraft: false # include draft (unreviewed) translations flatten: false # flatten nested keys to dot-notation
pushOptions: createMissing: true # create keys not yet in LokAI updateExisting: false # overwrite source text for existing keysFields
Section titled “Fields”version
Section titled “version”Required · number
Config file schema version. Always set to 1.
workspace
Section titled “workspace”Required · string
The slug of your LokAI workspace. Found in your workspace settings.
project
Section titled “project”Required · string
The slug of the project within the workspace to sync keys with.
apiUrl
Section titled “apiUrl”Optional · string · Default: https://api.lokai.cloud
Override the API base URL. Useful for self-hosted deployments or pointing at the development environment (https://api-dev.lokai.cloud).
localesDir
Section titled “localesDir”Required · string
Path to the directory containing your local translation files, relative to the config file.
format
Section titled “format”Required · string
File format used for import and export.
| Value | Description |
|---|---|
json | Flat or nested JSON |
yaml | YAML key-value files |
po | GNU gettext .po files |
xliff | XLIFF 1.2 / 2.0 |
mainLanguages
Section titled “mainLanguages”Required · string[]
BCP 47 language codes for the main (source) languages of the project. These are human-owned — the CLI pushes them to LokAI and the LLM translates from them.
targetLanguages
Section titled “targetLanguages”Required · string[]
BCP 47 language codes for languages owned by the LLM. The CLI pulls completed translations for these languages.
pullOptions.includeDraft
Section titled “pullOptions.includeDraft”Optional · boolean · Default: false
When true, the CLI pulls translations with draft status in addition to approved ones.
pullOptions.flatten
Section titled “pullOptions.flatten”Optional · boolean · Default: false
When true, nested JSON/YAML keys are flattened to dot-notation on pull (e.g. buttons.save instead of { buttons: { save: "..." } }).
pushOptions.createMissing
Section titled “pushOptions.createMissing”Optional · boolean · Default: true
When true, local keys not yet present in LokAI are created automatically on push.
pushOptions.updateExisting
Section titled “pushOptions.updateExisting”Optional · boolean · Default: false
When true, pushing will overwrite the source text of keys that already exist in LokAI. Use with caution — this will trigger re-translation for all affected keys.
Example — Minimal
Section titled “Example — Minimal”version: 1workspace: acme-corpproject: main-applocalesDir: ./src/localesformat: jsonmainLanguages: [en]targetLanguages: [fr, de, es]Example — Full
Section titled “Example — Full”version: 1workspace: acme-corpproject: main-appapiUrl: https://api.lokai.cloudlocalesDir: ./src/localesformat: jsonmainLanguages: - en - en-GBtargetLanguages: - fr - de - es - ja - zhpullOptions: includeDraft: false flatten: falsepushOptions: createMissing: true updateExisting: false