Auto Fill

Creation:2025-03-13Last update:2025-09-20

Fill Content Declaration File Translations

Autofill content declaration files in your CI are a way to speed up your development workflow.

Understanding the behavior

The fill command includes two modes:

• Complete: Automatically fill all missing content for each locale and edit the current file, or another file if specified. That say, complete mode will skip the translation of existing content, if already translated.
• Review: Automatically fill all content for each locale and generate for a specific file, or another file if specified.

The will command will process all your locale content declaration files. That say, it will not process your remote content from the CMS. The CMS includes its own translations management. If you use plugins as @intlayer/sync-json-plugin, Intlayer will transform the JSON files into a locale content declaration files. That say, they will be processed by the fill command.

The new generated files include a filled instruction as dictionary metadata. This instruction will be used by Intlayer to know if the file has been autofilled or not, and skip this file from being translated again if present.

Intlayer will also consider the following instruction for autofill:

• From your .content.{ts|js|json} → fill instruction
• From your configuration file .intlayer.config.ts → dictionary.fill instruction
• Will be set to true by default otherwise

For per-locale content declaration files, the true instruction will be replaced by ./{{fileName}}.fill.content.json. This is because the a per-locale content declaration file cannot receive additional localized content. So it will generate a new file to do not overwrite the existing file.

Default Behavior

By default, fill is set to true globally, which means Intlayer will automatically fill all content files and edit the file itself. This behavior can be customized in several ways:

Global Configuration Options

1. fill: true (default) - Automatically fill all locales and edit the current file
2. fill: false - Disable auto-fill for this content file
3. fill: "./relative/path/to/file" - Create/update the specified file without editing the current one by pointing to a relative path resolved based on the location of the current file
4. fill: "/absolute/path/to/file" - Create/update the specified file without editing the current one by pointing to an relative path resolved based on the location of base directory (field baseDir in the configuration file .intlayer.config.ts)
5. fill: "C:\absolute\path\to\file" - Create/update the specified file without editing the current one by pointing to an absolute path resolved based on your operating system
6. fill: { [key in Locales]?: string } - Create/update the specified file for each locale

v7 Behavior Changes

In v7, the fill command behavior has been updated:

• fill: true - Rewrites the current file with filled content for all locales
• fill: "path/to/file" - Fills the specified file without modifying the current file
• fill: false - Disables auto-fill completely

When using a path option to write to another file, the fill mechanism works through a master-slave relationship between content declaration files. The main (master) file serves as the source of truth, and when it's updated, Intlayer will automatically apply those changes to the derived (filled) declaration files specified by the path.

Per-Locale Customization

You can also customize the behavior for each locale by using an object:

This allows you to have different fill behaviors for different locales within the same project.

Here is a per-locale content declaration file using the fill instruction.

Then, when you run the following command:

Intlayer will automatically generate the derived declaration file at src/components/example/example.content.json, filling in all locales not already declared in the main file.

Afterward, both declaration files will be merged into a single dictionary, accessible using the standard useIntlayer("example") hook (react) / composable (vue).

Global Configuration

You can configure the global auto fill configuration in the intlayer.config.ts file.

You can still fine‑tune per dictionary using the fill field in content files. Intlayer will first consider the per dictionary configuration and then fallback to the global configuration.

Autofilled File Format

The recommended format for autofilled declaration files is JSON, which helps avoid formatting constraints. However, Intlayer also supports .ts, .js, .mjs, .cjs, and other formats.

This will generate the file at:

The generation of .js, .ts, and similar files works as follows:

• If the file already exists, Intlayer will parse it using the AST (Abstract Syntax Tree) to locate each field and insert any missing translations.
• If the file does not exist, Intlayer will generate it using the default content declaration file template.

Absolute Paths

The fill field also supports absolute paths.

This will generate the file at:

Autogenerate Per-Locale Content Declaration Files

The fill field also supports generation of per-locale content declaration files.

This will generate two separate files:

• src/components/example/example.fr.content.json
• src/components/example/example.es.content.json

In this case, if the object does not contain all locales, Intlayer skip the generation of the remaining locales.

Filter Specific Locale Autofill

Using an object for the fill field allows you to apply filters and generate only specific locale files.

This will only generate the French translation file.

Path Variables

You can use variables inside the fill path to dynamically resolve the target paths for the generated files.

Available variables:

• {{locale}} – Locale code (e.g. fr, es)
• {{fileName}} – File name (e.g. index)
• {{key}} – Dictionary key (e.g. example)

This will generate:

• /messages/fr/example.content.json
• /messages/es/example.content.json

This will generate:

• ./index.content.json
• ./index.content.json