---
createdAt: 2025-03-01
updatedAt: 2026-10-27
priority: 8
title: "Testing Your Translations with Intlayer"
description: "Test your Intlayer content: detect missing translations, validate dictionaries in CI and render components per locale in unit tests."
keywords:
- Testing
- Intlayer
- Internationalization
- CMS
- Content Management System
- Visual Editor
slugs:
- doc
- testing
history:
- version: 6.1.0
date: 2026-10-27
changes: "Clarify that content test exits non-zero on missing required locales"
- version: 6.0.1
date: 2025-10-05
changes: "Make test async and add build option"
- version: 6.0.0
date: 2025-09-20
changes: "Introduction of testing"
author: aymericzip
---
# Testing your content
This guide shows how to automatically verify your dictionaries are complete, catch missing translations before shipping, and test localized UI in your app.
## What you can test
- **Missing translations**: fail CI if any required locales are missing for any dictionary.
- **Localized UI rendering**: render components with a specific locale provider and assert on visible text/attributes.
- **Build-time audits**: run `npx intlayer content test` locally or in CI; it exits non-zero when required translations are missing.
## Quick start: audit via CLI
Run the audit from your project root:
```bash packageManager="npm"
npx intlayer content test
```
```bash packageManager="yarn"
yarn intlayer content test
```
```bash packageManager="pnpm"
pnpm intlayer content test
```
```bash packageManager="bun"
bun x intlayer content test
```
Useful flags:
- `--env-file [path]`: load environment variables from a file.
- `-e, --env [name]`: select an environment profile.
- `--base-dir [path]`: set the app base directory for resolution.
- `--verbose`: show verbose logs.
- `--prefix [label]`: prefix log lines.
- `--build [build]`: build the dictionaries before testing to ensure the content is up to date. True will force the build, false will skip the build, undefined will allow using the cache of the build.
The command exits with code `1` when any required locale is missing (see `requiredLocales` in your configuration), and `0` otherwise. You can use it directly to fail CI jobs or commit hooks. The programmatic test below is an optional alternative.
## Programmatic test (Vitest/Jest)
Use the Intlayer CLI API to assert there are no missing translations for your required locales.
```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) {
// Helpful when the test fails locally or in CI
console.log(result.missingTranslations);
}
expect(result.missingRequiredLocales).toHaveLength(0);
});
});
```
Jest equivalent:
```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) {
// Helpful when the test fails locally or in CI
console.log(result.missingTranslations);
}
expect(result.missingRequiredLocales).toHaveLength(0);
});
```
How it works:
- Intlayer reads your configuration (locales, requiredLocales) and declared dictionaries, then reports:
- `missingTranslations`: per‑key, which locales are missing and from which file.
- `missingLocales`: union of all missing locales.
- `missingRequiredLocales`: subset limited to `requiredLocales` (or all locales if `requiredLocales` is not set).
## Testing localized UI (React / Next.js)
Render components under an Intlayer provider and assert on visible content.
React example (Testing Library):
```tsx
import { IntlayerProvider } from "react-intlayer/client";
import { render, screen } from "@testing-library/react";
import { MyComponent } from "./MyComponent";
test("renders localized title in English", () => {
render(
);
expect(screen.getByText("Expected English title")).toBeInTheDocument();
});
```
Next.js (App Router) example: use the framework wrapper:
```tsx
import { IntlayerClientProvider } from "next-intlayer/client";
import { render, screen } from "@testing-library/react";
import { MyPage } from "./MyPage";
test("renders localized heading in French", () => {
render(
);
expect(
screen.getByRole("heading", { name: "Titre attendu" })
).toBeInTheDocument();
});
```
Tips:
- When you need raw string values for attributes (e.g., `aria-label`), access the `.value` field returned by `useIntlayer` in React.
- Keep dictionaries colocated with components for easier unit testing and cleanup.
## Continuous Integration
Run the CLI audit in CI. It fails the job when required translations are missing.
`package.json`:
```json
{
"scripts": {
"test:i18n": "npx intlayer content test"
}
}
```
Alternative: Vitest
```json
{
"scripts": {
"test:i18n": "vitest run"
}
}
```
GitHub Actions example:
```yaml
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npx intlayer content test
```
Optional: run the CLI audit for a human-readable summary alongside tests:
```bash packageManager="npm"
npx intlayer content test --verbose
```
```bash packageManager="yarn"
yarn intlayer content test --verbose
```
```bash packageManager="pnpm"
pnpm intlayer content test --verbose
```
```bash packageManager="bun"
bun x intlayer content test --verbose
```
## Troubleshooting
- Ensure your Intlayer configuration defines `locales` and (optionally) `requiredLocales`.
- If your app uses dynamic or remote dictionaries, run tests in an environment where the dictionaries are available.
- For mixed monorepos, use `--base-dir` to point the CLI at the correct application root.
---