Translation as file

File format value

translation-as-file

Copy value

List of supported file formats

Translation as file is a plain text file format that allows you to export (or import) every translation key into a single file. This file format is useful when you want to synchronize markdown blog posts, documentation, or any other content that is not stored in your codebase. Learn how to set up a complete workflow in Markdown translations.

This file format requires SimpleLocalize CLI version 2.8.0 or higher.

Translation key

Unlike the Markdown format, translation as file works with any text file, for example .mdx, .txt, .html, or .yml, and does not remove the file extension. The translation key is exactly the part of the file path matched by {translationKey} placeholder:

• --uploadPath ./content/{translationKey} uploads content/snippets/footer.html as the snippets/footer.html translation key,
• --uploadPath ./content/{translationKey}.html uploads the same file as the snippets/footer translation key.

Use the same pattern in the download path, so the files are saved with the same names.

Special placeholder

With the translation as file format, you have to use a special placeholder {translationKey} that will be replaced with the actual translation key value.

Upload and download ZIP files via Web UI

You don't need the CLI to translate many files. Put them in a ZIP archive and upload it in the Web UI:

1. Choose Translation as file as the file format and select the language of the files. All files in one ZIP must be in the same language.
2. Upload the ZIP file. Every file becomes one translation key, named after its full path in the archive including the extension, for example docs/guide/intro.mdx becomes the docs/guide/intro.mdx translation key.
3. Translate the content in the translation editor.
4. Export translations in the Translation as file format. When more than one file is exported, you get a ZIP archive with one folder per language and the same folder structure as the uploaded archive, for example de/docs/guide/intro.mdx.

A single ZIP archive can contain up to 200 files. Split larger sets of files into several archives.

Upload with CLI

Example command to upload plain text files:

simplelocalize upload --apiKey <PROJECT_API_KEY> \
  --uploadFormat translation-as-file \
  --uploadPath ./blog-posts/{lang}/{translationKey}.txt

{translationKey} will be replaced with the actual translation key value, and {lang} will be replaced with the actual language code.

Example command to upload plain text files:

simplelocalize upload --apiKey <PROJECT_API_KEY> \
  --uploadFormat translation-as-file \
  --uploadPath ./public/{translationKey}/{lang}.txt

Learn more about SimpleLocalize CLI and translations upload feature.

Download with CLI

Example command to download plain text files:

simplelocalize download --apiKey <PROJECT_API_KEY> \
  --downloadFormat translation-as-file \
  --downloadPath ./blog-posts/{lang}/{translationKey}.txt

Example command to download plain text files:

simplelocalize download --apiKey <PROJECT_API_KEY> \
  --downloadFormat translation-as-file \
  --downloadPath ./public/{translationKey}/{lang}.txt

Learn more about SimpleLocalize CLI and translations download feature.