@intlayer/docs 9.4.2 → 9.4.4

package/blog/en/date_time_number_formatting_locales.md

@@ -0,0 +1,216 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Formatting dates and numbers by locale with Intl"
+description: You probably do not need a formatting library. How Intl handles dates, numbers, currency and lists per locale, the caching cost, and the timezone bug that only breaks in production.
+keywords:
+  - format date by locale
+  - Intl.DateTimeFormat
+  - Intl.NumberFormat
+  - toLocaleDateString
+  - locale currency format
+  - relative time format
+slugs:
+  - blog
+  - date-time-number-formatting-locales
+author: aymericzip
+---
+
+# Formatting dates and numbers by locale with Intl
+
+Translating strings is the visible half of i18n. The half that generates bug reports is formatting: a German user seeing `1,234.56` instead of `1.234,56`, a Japanese user seeing `08/02/2026` and reading it as August, or a date that renders differently on the server and the client and takes the page down on hydration.
+
+None of that needs a library. `Intl` is in every runtime you target.
+
+## Table of Contents
+
+<TOC/>
+
+## Start by deleting your date helper
+
+Almost every codebase has a `formatDate` written before anyone thought about locales. It hardcodes an order, a separator, and usually English month names.
+
+```ts
+// The thing to delete.
+const formatDate = (d: Date) =>
+  `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`;
+```
+
+`Intl.DateTimeFormat` replaces it and is correct in every locale:
+
+```ts
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// "2. August 2026"
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(date);
+// "2026年8月2日"
+```
+
+The same applies to numbers. `toFixed(2)` produces `1234.56` everywhere, which is wrong in most of Europe.
+
+## What `Intl` covers
+
+| API                       | Use it for                                              |
+| :------------------------ | :------------------------------------------------------ |
+| `Intl.DateTimeFormat`     | Dates and times, with `dateStyle` / `timeStyle` presets |
+| `Intl.NumberFormat`       | Decimals, currency, percent, units, compact notation    |
+| `Intl.RelativeTimeFormat` | "3 days ago", "in 2 hours"                              |
+| `Intl.ListFormat`         | "a, b, and c" versus "a, b et c"                        |
+| `Intl.PluralRules`        | Which plural category a number falls into               |
+| `Intl.Collator`           | Sorting strings correctly per language                  |
+
+`Intl.Collator` is the one people forget. `array.sort()` on strings uses code point order, so accented characters sort after `z` and Swedish `ö` lands in the wrong place. If you sort user-visible lists, sort with a collator.
+
+```ts
+["zebra", "édouard", "apple"].sort(new Intl.Collator("fr").compare);
+// ["apple", "édouard", "zebra"]
+```
+
+## Prefer presets to hand-built options
+
+`dateStyle` and `timeStyle` let the locale decide the order and separators. Specifying `year`, `month` and `day` individually gives you control you usually should not want, because the correct order differs by locale and you are overriding CLDR data with your own assumption.
+
+```ts
+// Locale decides the shape.
+new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(d);
+
+// You decided the shape, and you are wrong somewhere.
+new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+}).format(d);
+```
+
+Use explicit components only when the design genuinely requires a fixed shape, for instance a table column that must stay narrow.
+
+## Constructing formatters is expensive
+
+This is the performance detail that matters. Building an `Intl.NumberFormat` involves loading locale data, and it is far more expensive than the `format()` call that follows. Doing it inside a render or a loop over a thousand rows is a measurable cost.
+
+```ts
+// Rebuilds the formatter on every row.
+rows.map((r) => new Intl.NumberFormat(locale).format(r.total));
+
+// Build once, reuse.
+const nf = new Intl.NumberFormat(locale);
+rows.map((r) => nf.format(r.total));
+```
+
+`toLocaleDateString()` and `toLocaleString()` have the same problem hidden inside them: each call constructs a formatter. They are fine for one value and wrong for a list.
+
+Cache by the combination of locale and options, since those are what define a formatter:
+
+```ts
+const cache = new Map<string, Intl.NumberFormat>();
+
+const getNumberFormat = (
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+) => {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, options);
+    cache.set(key, formatter);
+  }
+  return formatter;
+};
+```
+
+## The timezone bug that only appears in production
+
+This one costs entire afternoons. A server renders a date, the browser hydrates it, and React throws a hydration mismatch because the two produced different text.
+
+The cause is that `Intl.DateTimeFormat` uses the ambient timezone when you do not name one. Your production server runs in UTC. Your laptop does not. So the bug is invisible locally and reproducible only in production, which is the worst possible combination.
+
+```ts
+// Server in UTC and a browser in UTC+9 disagree. Hydration mismatch.
+new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(d);
+
+// Both agree.
+new Intl.DateTimeFormat(locale, { dateStyle: "short", timeZone: "UTC" }).format(
+  d
+);
+```
+
+Three workable approaches:
+
+- **Pin a timezone** on the server and pass it explicitly. Correct and deterministic, but everyone sees UTC.
+- **Render on the client only**, with a stable placeholder for the server pass. Correct per user, costs a flash.
+- **Store the user's timezone** and pass it on both sides. Best result, most work.
+
+Whichever you pick, always pass `timeZone` explicitly for any date rendered on both server and client. A date with no timezone is a date with two values.
+
+## Currency needs a currency, not a locale
+
+Locale and currency are independent. `fr-FR` does not mean euros: a French user can be looking at a USD invoice.
+
+```ts
+new Intl.NumberFormat("fr-FR", { style: "currency", currency: "USD" }).format(
+  1234.5
+);
+// "1 234,50 $US"
+```
+
+The locale controls the separators, digit grouping and symbol placement. The currency comes from your data. Deriving one from the other is a bug that reaches accounting.
+
+Also note `currencyDisplay`. In an interface where several currencies coexist, `"code"` removes the ambiguity between US, Canadian and Australian dollars.
+
+## Relative time reads better than absolute time
+
+For anything recent, "2 hours ago" beats a timestamp, and `Intl.RelativeTimeFormat` localizes it properly.
+
+```ts
+new Intl.RelativeTimeFormat("es", { numeric: "auto" }).format(-1, "day");
+// "ayer"
+```
+
+`numeric: "auto"` is what produces "yesterday" instead of "1 day ago". Without it you get the numeric form in every language, which reads like a machine.
+
+## What Intlayer adds
+
+Intlayer wraps these in cached helpers so you do not maintain the map above, and so the active locale is applied by default rather than passed at every call site.
+
+```ts
+import {
+  number,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+  list,
+} from "intlayer";
+
+number(1234.5); // "1,234.5"
+currency(1234.5, { currency: "EUR" }); // "€1,234.50"
+date(new Date(), "short");
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"
+units(5, { unit: "kilometer", unitDisplay: "long" }); // "5 kilometers"
+compact(1200); // "1.2K"
+list(["apple", "banana", "orange"]); // "apple, banana, and orange"
+```
+
+`date()` also accepts presets (`"short"`, `"long"`, `"dateOnly"`, `"timeOnly"`, `"full"`) so the common cases do not need an options object. React and Vue equivalents exist as hooks and composables, which resolve the active locale from context instead of taking it as an argument.
+
+To be clear about what this is: a caching layer and a locale default over the platform API. The formatting behaviour is `Intl`, and everything in this post applies whether or not you use it. Full signatures in the [formatters documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/formatters.md).
+
+## Common mistakes
+
+- **`toLocaleDateString()` with no locale.** Uses the runtime's locale, which on a server is whatever the container was configured with.
+- **Formatting in a loop.** Constructing the formatter dominates the cost. Build once.
+- **No `timeZone` on isomorphic dates.** Hydration mismatch that never reproduces on your machine.
+- **Deriving currency from locale.** `fr-FR` is not euros.
+- **`sort()` on user-visible strings.** Use `Intl.Collator`.
+- **Hardcoding month or day names.** They are in CLDR already, in every language.
+- **`numeric: "always"` for relative time.** "1 day ago" where every language has a word for yesterday.
+
+## Going further
+
+- [Formatters and locale utilities: `number`, `currency`, `date`, `relativeTime`, `list`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/formatters.md)
+- [Configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+- [Benchmark reports across frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md)
+- [Drop-in react-intl compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/react-intl.md)
+- [ICU message format: plurals, select and number skeletons](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/icu_message_format.md)
+- [How to test translations, including formatter and plural coverage](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/i18n_testing_strategies.md)
+- [What internationalization actually covers](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/what_is_internationalization.md)

package/blog/en/detecting_missing_translations.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "How to find missing translations before your users do"
+description: Missing translations fail silently. Why fallback hides them, the four detection layers that actually work, and how to fail a build on an untranslated key.
+keywords:
+  - find missing translations
+  - missing translation keys
+  - i18n audit
+  - untranslated strings
+  - translation coverage
+  - i18n lint
+slugs:
+  - blog
+  - detecting-missing-translations
+author: aymericzip
+---
+
+# How to find missing translations before your users do
+
+A missing translation almost never throws. Depending on your setup it either shows the English string to a Japanese user, or prints `checkout.summary.total` on a live page. Both ship, both pass code review, and both are found by a customer rather than by you.
+
+## Table of Contents
+
+<TOC/>
+
+## This applies whatever library you use
+
+Nothing here is specific to one stack. The detection layers below work the same on i18next, react-i18next, next-intl, react-intl, vue-i18n, next-translate or Lingui, because they all resolve keys the same way and all fail the same way.
+
+The tooling is portable too. If your messages live in JSON catalogs today, the [Sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-json.md) points Intlayer at those files, so you get the audit, fill and test commands without moving your content or changing a single import:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // or "icu" for next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+If you want the runtime API to stay identical as well, the [compat adapters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md) alias `useTranslation`, `$t` and friends at the bundler level. Either way, treat the commands below as one implementation of the idea, not as a requirement.
+
+## Why they are invisible
+
+Every i18n library resolves a key through the same chain: look up the active locale, fall back to a default, and if that fails, return the key itself. That last step is the problem. There is no error, no warning in production, and no failing test, because nothing in the pipeline treats a missing key as abnormal.
+
+Fallback makes it worse, not better. A page that silently renders in English looks fine to an English-speaking developer and to every automated check you have. The bug is only visible to the person who cannot read the result.
+
+So the question is not "how do I handle missing translations at runtime". It is "how do I make a missing translation impossible to merge".
+
+## The four places you can catch them
+
+Each layer catches something the others cannot. You want more than one.
+
+| Layer           | Catches                                      | Misses                                        |
+| :-------------- | :------------------------------------------- | :-------------------------------------------- |
+| Types           | Keys that do not exist at all                | A key that exists but is untranslated in `ja` |
+| Lint            | Hardcoded strings never sent for translation | Keys missing from a catalog                   |
+| Audit           | Locale coverage across every declared key    | Text that was never made translatable         |
+| Rendering tests | Keys that resolve but render wrong           | Everything not covered by a test              |
+
+The gap most teams have is the third row: they know their keys are valid, but nothing checks that all eighteen locales actually have a value.
+
+## Layer 1: make the key a type, not a string
+
+`t("checkout.summry.total")` is a typo that compiles. If your keys are plain strings, every rename is a runtime risk and every deletion leaves an orphan.
+
+Typed keys turn that into a build error. `react-i18next` supports it through declaration merging, `next-intl` infers from your message shape, Lingui derives IDs from the source text, and Intlayer generates types from the declaration files. All of them work; what differs is how much you have to wire up.
+
+This layer is necessary and not sufficient. Types describe the shape of your default catalog. They say nothing about whether Korean has a value for that key.
+
+## Layer 2: lint the strings that never became keys
+
+The translation you cannot find is often the one that was never externalized. A hardcoded label in a component is invisible to every catalog-based audit, because as far as the tooling is concerned it does not exist.
+
+Intlayer's ESLint plugin covers this with `no-raw-text`, plus `no-unused-content` for the reverse case: content declared and no longer read by anything.
+
+```js fileName="eslint.config.mjs"
+import intlayer from "@intlayer/eslint-plugin";
+
+export default [
+  intlayer.configs.recommended,
+  {
+    rules: {
+      "@intlayer/no-raw-text": "error",
+      "@intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+`no-unused-content` is the one that keeps catalogs from growing forever. Dead keys are not a correctness bug, but they are what makes a translation vendor invoice larger than it should be. Full rule list in the [ESLint plugin doc](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/eslint.md).
+
+## Layer 3: audit locale coverage
+
+This is the layer that answers the actual question. Intlayer ships it as a CLI command:
+
+```bash packageManager="npm"
+npx intlayer content test
+```
+
+It reads your configured locales and declared dictionaries, then reports which keys are missing which locales, and in which file.
+
+One detail worth knowing before you wire it into anything: **the CLI prints a report but does not exit non-zero on failure.** If you drop it into a pipeline expecting a red build, you will get a green one with a wall of text nobody reads. For gating, use the programmatic API instead, covered below.
+
+## Layer 4: assert it in the test suite
+
+`listMissingTranslations()` gives you the same audit as data, which is what you want for a build gate.
+
+```ts fileName="i18n.test.ts"
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("has no missing required locales", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Three fields come back, and the distinction matters:
+
+- `missingTranslations`: per key, which locales are missing and from which file. This is what you print when the test fails.
+- `missingLocales`: the union across every key.
+- `missingRequiredLocales`: restricted to `requiredLocales` in your config, or all locales if you have not set it.
+
+## Required locales are the useful knob
+
+Shipping eighteen locales does not mean all eighteen must be complete to deploy. Most teams have a tier that blocks a release and a tier that is best-effort.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.JAPANESE,
+      Locales.POLISH,
+    ],
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Without `requiredLocales`, every declared locale is required and your build stays red until the last language lands. That is usually how teams end up disabling the check entirely, which is worse than not having it.
+
+## Finding the ones already in production
+
+The layers above prevent new gaps. For an app that already shipped, two things help.
+
+**Pseudolocalization.** Run a locale where every string is transformed, for example `[!!! Ĉĥéçķöũţ !!!]`. Anything rendering in plain English is hardcoded. It finds in ten minutes what a catalog audit structurally cannot see, because it tests the rendered page rather than the catalog.
+
+**Crawl your own site.** If you serve localized URLs, fetch a sample per locale and grep the HTML for your default-language strings. A page in `/ja/` containing "Add to cart" is either a missing translation or a fallback you did not know about.
+
+```bash
+curl -s https://example.com/ja/checkout | grep -c "Add to cart"
+```
+
+## Filling the gaps
+
+Once you know what is missing, `intlayer fill` populates the empty entries, and the `autoFill` option can generate per-locale files as content is declared. See [autoFill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/autoFill.md).
+
+Worth being clear-eyed about this: machine-filled translations turn a _visible_ gap into an _invisible_ one. The key now has a value, so the audit goes green, and nobody reviews the wording. Use it to unblock a release, then route the output through a human for anything a customer reads before deciding. It is a scaffold, not an answer.
+
+## Common mistakes
+
+- **Treating fallback as a feature.** It is a rendering strategy, not a safety net. A silent English page is a bug that reports itself to nobody.
+- **Relying on the CLI report to gate CI.** `intlayer content test` exits zero regardless. Assert in a test.
+- **Requiring every locale.** The check gets disabled the first time a release is blocked by a half-finished language.
+- **Auditing catalogs but never the rendered page.** Hardcoded strings are invisible to a catalog audit by definition.
+- **Checking only the default locale in tests.** That is the one locale that cannot be missing.
+- **Letting machine fill close the loop.** Green audit, unreviewed copy.
+
+## Going further
+
+- [Testing your content: CLI audit, programmatic API and UI assertions](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/testing.md)
+- [ESLint plugin rules, including `no-raw-text` and `no-unused-content`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/eslint.md)
+- [autoFill: generating per-locale declaration files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/autoFill.md)
+- [Configuration reference: `locales`, `requiredLocales`, `defaultLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+- [Benchmark reports across frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md)
+- [Drop-in i18next compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/i18next.md)
+- [What internationalization actually covers](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/what_is_internationalization.md)
+- [Per-component vs centralized i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/per-component_vs_centralized_i18n.md)

package/blog/en/i18n_in_ci_cd_pipelines.md

@@ -0,0 +1,247 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Automating translations in CI/CD without shipping bad copy"
+description: Three places to automate i18n, pre-push, pull request and runtime. How to gate a build on coverage, auto-fill safely, and avoid the CI loop that commits forever.
+keywords:
+  - automate translations ci
+  - i18n ci cd
+  - github actions translations
+  - husky pre-push
+  - continuous localization
+  - translation pipeline
+slugs:
+  - blog
+  - i18n-in-ci-cd-pipelines
+author: aymericzip
+---
+
+# Automating translations in CI/CD without shipping bad copy
+
+Manual translation does not survive contact with a release cadence. Someone adds a string on Friday, the export happens next sprint, and by then three more locales are behind. Automating it is straightforward. Automating it without quietly publishing machine output to customers is the part worth thinking about.
+
+## Table of Contents
+
+<TOC/>
+
+## You do not have to migrate to automate
+
+The pipeline shapes below are library-agnostic, and so is the tooling. If your messages are JSON catalogs for i18next, next-intl, react-intl, vue-i18n or next-translate, the [Sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-json.md) reads and writes those files in place:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // or "icu" for next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Your app keeps importing what it imports. The CI jobs below then fill and gate your existing catalogs, and the diff a reviewer sees is a change to `locales/fr/checkout.json`, not a migration. There is a [Sync PO plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-po.md) for gettext workflows, and [compat adapters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md) if you also want the runtime API to stay unchanged.
+
+## Separate the gate from the fill
+
+Two different jobs get confused constantly.
+
+A **gate** is a check that fails. It says this build must not ship because required locales are missing. It writes nothing.
+
+A **fill** is a mutation. It generates the missing translations and commits them. It never fails a build.
+
+Running only a fill means nothing ever blocks, and machine output flows to production unreviewed. Running only a gate means the build goes red and a human has to unblock it every time. Most teams want both, wired to different triggers: fill on a pull request, gate on merge to the release branch.
+
+## Where automation can live
+
+| Stage          | Trigger   | Good for                                   | Cost                                              |
+| :------------- | :-------- | :----------------------------------------- | :------------------------------------------------ |
+| Pre-push hook  | Local git | Fast feedback, no CI minutes               | Runs on the developer's machine and their API key |
+| Pull request   | CI job    | Review before merge, one place for secrets | CI minutes plus model calls per PR                |
+| Release branch | CI job    | Hard gate on coverage                      | Cheap, no model calls                             |
+| Runtime        | CMS       | Content changes without a rebuild          | Hosted dependency                                 |
+
+## Pre-push: fastest loop
+
+Husky runs the fill before the code leaves the machine, so the translations arrive in the same push as the strings that needed them.
+
+```bash fileName=".husky/pre-push"
+npx intlayer build
+npx intlayer fill --unpushed --mode complete
+```
+
+`--unpushed` limits the work to content that has not been pushed yet, which is what keeps this from taking a minute on every push. `--mode complete` fills what is missing without rewriting entries that already have a value, so a reviewed translation is never silently replaced.
+
+For a monorepo, scope each app:
+
+```bash fileName=".husky/pre-push"
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
+```
+
+The downside is real: every developer needs an API key, and the cost lands on whoever pushes. That is why most teams move this to CI once there are more than a few of them.
+
+## Pull request: fill where the review is
+
+The same work in GitHub Actions, scoped to the diff:
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "autofill-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npx intlayer build
+      - run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+      - name: Commit
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git config --local user.email "action@github.com"
+            git config --local user.name "GitHub Action"
+            git add .
+            git commit -m "chore: auto-fill missing translations [skip ci]"
+            git push origin HEAD:${{ github.head_ref }}
+          fi
+```
+
+Four details in there are load-bearing:
+
+- **`fetch-depth: 0`** is required for `--git-diff` to work. A shallow clone has no base to diff against, and the fill silently covers nothing.
+- **`[skip ci]` in the commit message** stops the workflow retriggering itself. Without it the job commits, which opens a run, which commits again. This is the classic way to burn a CI budget overnight.
+- **`concurrency` with `cancel-in-progress`** stops two pushes racing to write the same files.
+- **`--git-diff`** scopes the fill to what changed in the PR. Omit it and you re-translate the whole catalog on every run.
+
+The translations land as a commit on the PR branch, which means a reviewer sees them in the diff. That is the entire point of doing it here rather than after merge.
+
+## Release branch: the gate
+
+The gate needs no model access and should be fast.
+
+```yaml fileName=".github/workflows/ci.yml"
+- run: npm run test:i18n
+```
+
+Backed by a test that asserts coverage rather than by the CLI report:
+
+```ts fileName="i18n.test.ts"
+import { listMissingTranslations } from "intlayer/cli";
+
+test("has no missing required locales", async () => {
+  const result = await listMissingTranslations();
+  if (result.missingRequiredLocales.length > 0) {
+    console.log(result.missingTranslations);
+  }
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+`npx intlayer content test` prints a report but exits zero, so it informs and does not gate. Use it locally; use the assertion in CI. More on the distinction in [finding missing translations](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/detecting_missing_translations.md).
+
+## `requiredLocales` is what makes the gate survivable
+
+A gate that demands all eighteen locales blocks every release until the slowest language lands, and gets disabled within a month.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Declare the locales you serve, require the ones that block a release. The rest are filled asynchronously and never hold up a deploy.
+
+## Taking translations out of the repo entirely
+
+The other model is to declare one locale in code and manage the rest remotely, through the CMS with Live Sync. Content changes then do not require a rebuild at all, which decouples the copy cadence from the deploy cadence.
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    liveSync: true,
+  },
+};
+
+export default config;
+```
+
+This suits teams where non-developers own the copy. It is a trade, not an upgrade: you gain editor autonomy and lose the property that a git checkout fully describes what the app renders. Details in the [CMS documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md).
+
+Note that `clientSecret` is a server-side credential. It belongs in CI secrets and in your server environment, never in anything that reaches a client bundle.
+
+## The honest limitation
+
+Everything above automates _coverage_, not _quality_. A machine fill turns a visible gap into an invisible one: the audit goes green because the key now has a value, and nobody read it.
+
+That is acceptable for an internal tool, a changelog, or a beta locale. It is not acceptable for pricing, legal copy, error messages that tell someone their payment failed, or anything a customer reads before deciding. Route those through a human, and use `--mode complete` everywhere so a reviewed string is never overwritten by a later run.
+
+Give the model context so its output is at least consistent:
+
+```ts
+ai: {
+  applicationContext: "B2B invoicing app. Formal register. Never translate the product name.",
+}
+```
+
+## Common mistakes
+
+- **No `[skip ci]` on the auto-commit.** The job retriggers itself in a loop.
+- **Shallow clone with `--git-diff`.** No base to diff, so nothing is filled and nothing complains.
+- **Filling the whole catalog every run.** Scope with `--git-diff` or `--unpushed` or watch the bill.
+- **Using the CLI report as a gate.** It exits zero.
+- **Requiring every locale.** The gate gets removed the first time it blocks a release.
+- **A fill job with no gate anywhere.** Nothing ever fails, so machine copy reaches production unreviewed.
+- **Model API keys in the repo.** They belong in CI secrets, same as `clientSecret`.
+
+## Going further
+
+- [CI/CD: auto-generating translations with Husky, GitHub Actions and the CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/CI_CD.md)
+- [Testing your content and gating a build on coverage](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/testing.md)
+- [autoFill: generating per-locale declaration files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/autoFill.md)
+- [Configuration reference: `locales`, `requiredLocales`, `editor`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+- [Benchmark reports across frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md)
+- [Drop-in i18next compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/i18next.md)
+- [How to find missing translations](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/detecting_missing_translations.md)
+- [How to test translations without brittle tests](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/i18n_testing_strategies.md)

package/blog/en/i18n_meaning.md

@@ -19,8 +19,6 @@ author: aymericzip
 
 # i18n Meaning: What is Internationalization and Why Does it Matter?
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## Understanding the "i18n" Meaning
 
 If you are involved in software development, web design, or digital marketing, you have likely encountered the term **i18n**. The true **i18n meaning** is simply a numeronym for **internationalization**.