Testare i tuoi contenuti

Questa guida mostra come verificare automaticamente che i tuoi dizionari siano completi, individuare traduzioni mancanti prima della distribuzione e testare l'interfaccia localizzata nella tua app.

Cosa puoi testare

• Traduzioni mancanti: fallire il CI se mancano locali richiesti in qualsiasi dizionario.
• Rendering dell'interfaccia localizzata: renderizzare componenti con un provider di locale specifico e verificare il testo/attributi visibili.
• Audit a tempo di build: eseguire npx intlayer content test localmente o in CI; termina con un codice diverso da zero quando mancano traduzioni richieste.

Avvio rapido: audit tramite CLI

Esegui l'audit dalla radice del tuo progetto:

npx intlayer content test

Flag utili:

• --env-file [path]: carica variabili d'ambiente da un file.
• -e, --env [name]: seleziona un profilo ambiente.
• --base-dir [path]: imposta la directory base dell'app per la risoluzione.
• --verbose: mostra log dettagliati.
• --prefix [label]: aggiunge un prefisso alle righe di log.

Il comando termina con il codice 1 quando manca un locale richiesto (vedi requiredLocales nella tua configurazione), e con 0 altrimenti. Puoi usarlo direttamente per far fallire job CI o hook di commit. Il test programmatico qui sotto è un'alternativa opzionale.

Test programmatico (Vitest/Jest)

Usa l'API CLI di Intlayer per verificare che non ci siano traduzioni mancanti per i locali richiesti.

/* @vitest-environment node */
import { listMissingTranslations } from "intlayer/cli";
import { describe, expect, it } from "vitest";

describe("traduzioni", () => {
  it("non ha locali richiesti mancanti", () => {
    const result = listMissingTranslations();

    if (result.missingRequiredLocales.length > 0) {
      // Utile quando il test fallisce localmente o in CI
      console.log(result.missingTranslations);
    }

    expect(result.missingRequiredLocales).toHaveLength(0);
  });
});

Equivalente Jest:

import { listMissingTranslations } from "intlayer/cli";

test("non ha locali richiesti mancanti", () => {
  const result = listMissingTranslations();

  if (result.missingRequiredLocales.length > 0) {
    console.log(result.missingTranslations);
  }

  expect(result.missingRequiredLocales).toHaveLength(0);
});

Come funziona:

• Intlayer legge la tua configurazione (locali, requiredLocales) e i dizionari dichiarati, quindi riporta:
  • missingTranslations: per chiave, quali locali mancano e da quale file.
  • missingLocales: unione di tutti i locali mancanti.
  • missingRequiredLocales: sottoinsieme limitato a requiredLocales (o tutti i locali se requiredLocales non è impostato).

Testare l'interfaccia localizzata (React / Next.js)

Renderizza i componenti sotto un provider Intlayer e verifica il contenuto visibile.

Esempio React (Testing Library):

import { IntlayerProvider } from "react-intlayer/client";
import { render, screen } from "@testing-library/react";
import { MyComponent } from "./MyComponent";

test("renders localized title in English", () => {
  render(
    <IntlayerProvider locale="en-US">
      <MyComponent />
    </IntlayerProvider>
  );

  expect(screen.getByText("Titolo inglese previsto")).toBeInTheDocument();
});

Esempio Next.js (App Router): usa il wrapper del framework:

import { IntlayerClientProvider } from "next-intlayer/client";
import { render, screen } from "@testing-library/react";
import { MyPage } from "./MyPage";

test("renderizza l'intestazione localizzata in francese", () => {
  render(
    <IntlayerClientProvider locale="fr-FR">
      <MyPage />
    </IntlayerClientProvider>
  );
  expect(
    screen.getByRole("heading", { name: "Titre attendu" })
  ).toBeInTheDocument();
});

Consigli:

• Quando hai bisogno dei valori stringa grezzi per gli attributi (es. aria-label), accedi al campo .value restituito da useIntlayer in React.
• Mantieni i dizionari accanto ai componenti per facilitare i test unitari e la pulizia.

Integrazione Continua

Esegui l'audit CLI in CI. Fa fallire il job quando mancano traduzioni richieste.

package.json:

{
  "scripts": {
    "test:i18n": "npx intlayer content test"
  }
}

Alternativa: Vitest

{
  "scripts": {
    "test:i18n": "vitest run"
  }
}

Esempio GitHub Actions:

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

Opzionale: esegui l'audit CLI per un riepilogo leggibile dall'uomo insieme ai test:

npx intlayer content test --verbose

Risoluzione dei problemi

• Assicurati che la tua configurazione Intlayer definisca locales e (opzionalmente) requiredLocales.
• Se la tua app utilizza dizionari dinamici o remoti, esegui i test in un ambiente dove i dizionari sono disponibili.
• Per monorepo misti, usa --base-dir per indicare al CLI la radice corretta dell'applicazione.