--- createdAt: 2024-08-11 updatedAt: 2026-09-27 priority: 5 title: "intlayer doc translate: Translate Markdown Docs" description: Learn how to automatically translate documentation files using AI translation services. keywords: - Translate - Document - Documentation - AI - CLI - Intlayer slugs: - doc - concept - cli - doc-translate author: aymericzip --- # Translate Document The `doc translate` command automatically translates documentation files from a base locale to target locales using AI translation services. ## Key Points: - Split large markdown files into chunks to stay within the AI model's context window limits. - Retry translation if the output format is incorrect. - Incorporates application and file-specific context for improved translation accuracy. - Preserves existing translations by not overwriting them. - Processes files, chunks, and locales in parallel using a queue system to increase speed. ```bash packageManager="npm" npx intlayer doc translate ``` ```bash packageManager="yarn" yarn intlayer doc translate ``` ```bash packageManager="pnpm" pnpm intlayer doc translate ``` ```bash packageManager="bun" bun x intlayer doc translate ``` ## Arguments: **File list options:** - **`--doc-pattern [docPattern...]`**: Glob patterns to match documentation files to translate. > Example: `npx intlayer doc translate --doc-pattern "docs/**/*.md" "src/**/*.mdx"` - **`--excluded-glob-pattern [excludedGlobPattern...]`**: Glob patterns to exclude from translation. > Example: `npx intlayer doc translate --excluded-glob-pattern "docs/internal/**"` - **`--skip-if-modified-before [skipIfModifiedBefore]`**: Skip the file if it has been modified before the given time. - Can be an absolute time as "2025-12-05" (string or Date) - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour) - This option check update time of the file using the `fs.stat` method. So it could be impacted by Git or other tools that modify the file. > Example: `npx intlayer doc translate --skip-if-modified-before "2025-12-05"` - **`--skip-if-modified-after [skipIfModifiedAfter]`**: Skip the file if it has been modified within the given time. - Can be an absolute time as "2025-12-05" (string or Date) - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour) - This option check update time of the file using the `fs.stat` method. So it could be impacted by Git or other tools that modify the file. > Example: `npx intlayer doc translate --skip-if-modified-after "2025-12-05"` - **`--skip-if-exists`**: Skip the file if it already exists. > Example: `npx intlayer doc translate --skip-if-exists` **Entry output options:** - **`--locales [locales...]`**: Target locales to translate documentation to. > Example: `npx intlayer doc translate --locales fr es de` - **`--base-locale [baseLocale]`**: Source locale to translate from. > Example: `npx intlayer doc translate --base-locale en` **File processing options:** - **`--nb-simultaneous-file-processed [nbSimultaneousFileProcessed]`**: Number of files to process simultaneously for translation. > Example: `npx intlayer doc translate --nb-simultaneous-file-processed 5` **AI options:** - **`--model [model]`**: The AI model to use for translation (e.g., `gpt-3.5-turbo`). - **`--provider [provider]`**: The AI provider to use for translation. - **`--temperature [temperature]`**: Temperature setting for the AI model. - **`--api-key [apiKey]`**: Provide your own API key for the AI service. - **`--application-context [applicationContext]`**: Provide additional context for the AI translation. - **`--data-serialization [dataSerialization]`**: The data serialization format to use for the AI features of Intlayer. Options: `json` (standard, reliable), `toon` (fewer tokens, less consistent). - **`--custom-prompt [prompt]`**: Customize the base prompt used for translation. (Note: For most use cases, the `--custom-instructions` option is recommended instead as it provides better control over translation behavior.) > Example: `npx intlayer doc translate --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "My application is a cat store"` **Environment variables options:** - **`--env`**: Specify the environment (e.g., `development`, `production`). - **`--env-file [envFile]`**: Provide a custom environment file to load variables from. - **`--base-dir`**: Specify the base directory for the project. - **`--no-cache`**: Disable the cache. > Example: `npx intlayer doc translate --base-dir ./docs --env-file .env.production.local` - **`--ci`**: Run the command in every Intlayer project of the monorepo (or only the current one when run from a project directory). Per-project credentials can be injected via `INTLAYER_PROJECT_CREDENTIALS`, a JSON map of project path to `{ "clientId", "clientSecret" }`. > Example: `npx intlayer doc translate --ci` **Log options:** - **`--verbose`**: Enable verbose logging for debugging. (default to true using CLI) > Example: `npx intlayer doc translate --verbose` **Custom instructions options:** - **`--custom-instructions [customInstructions]`**: Custom instructions added to the prompt. Usefull to apply specific rules regarding formatting, urls translation, etc. - Can be an absolute time as "2025-12-05" (string or Date) - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour) - This option check update time of the file using the `fs.stat` method. So it could be impacted by Git or other tools that modify the file. > Example: `npx intlayer doc translate --custom-instructions "Avoid translating urls, and keep the markdown format"` > Example: `npx intlayer doc translate --custom-instructions "$(cat ./instructions.md)"` **Git options:** - **`--git-diff`**: Only run on dictionaries that includes changes from base (default `origin/main`) to current branch (default: `HEAD`). - **`--git-diff-base`**: Specify the base reference for git diff (default `origin/main`). - **`--git-diff-current`**: Specify the current reference for git diff (default: `HEAD`). - **`--uncommitted`**: Include uncommitted changes. - **`--unpushed`**: Include unpushed changes. - **`--untracked`**: Include untracked files. > Example: `npx intlayer doc translate --git-diff --git-diff-base origin/main --git-diff-current HEAD` > Example: `npx intlayer doc translate --uncommitted --unpushed --untracked` > Note that the output file path will be determined by replacing the following patterns > > - `/{{baseLocale}}/` by `/{{locale}}/` (Unix) > - `\{{baseLocale}}\` by `\{{locale}}\` (Windows) > - `_{{baseLocale}}.` by `_{{locale}}.` > - `{{baseLocale}}_` by `{{locale}}_` > - `.{{baseLocaleName}}.` by `.{{localeName}}.` > > If the pattern is not found, the output file will add the `.{{locale}}` at the extensions of the file. `./my/file.md` will be translated to `./my/file.fr.md` for the French locale.