Verifica los tipos de las llamadas a mensajes

Genera e incluye declaraciones que verifiquen las cadenas de origen, los contextos y los valores de los mensajes mientras editas.

Una llamada a un mensaje puede ser válida en TypeScript y aun así solicitar la entrada equivocada del catálogo. Un cambio de contexto o un marcador de posición mal escrito puede hacer que el texto de origen o {name} aparezcan en pantalla. La extracción genera declaraciones que incorporan los mensajes de origen conocidos al sistema de tipos de la aplicación.

Genera la declaración e inclúyela #

Con la CLI instalada, ejecuta:

sh
npx lingo extract --src src --source-locale en

Los archivos de salida predeterminados son locales/en.jsonc y lingo.d.ts. Agrega lingo.d.ts a la lista de inclusión tsconfig existente de la aplicación si ninguno de los patrones actuales lo incluye. Conserva las demás entradas:

json
{
  "include": ["src", "lingo.d.ts"]
}

Ejecuta la verificación de tipos habitual de la aplicación. Una declaración que queda fuera del proyecto del compilador no restringe ninguna llamada. Si la extracción usa --types o i18n.typesPath, incluye la ruta de salida que corresponda.

Qué significa la interfaz generada #

El archivo amplía LingoMessages con las cadenas de origen y sus opciones. Este ejemplo muestra la estructura generada:

ts
export {};

declare module "@lingo.dev/react" {
  interface LingoMessages {
    "Hello, {name}.": {
      values: { name: string | number };
      context: "Greeting on the account dashboard";
    };
    "Save": {
      context: "Submit settings" | "Bookmark an article";
    };
  }
}

Vuelve a generar este archivo en lugar de mantener el ejemplo manualmente. El saludo ahora requiere values.name y su contexto extraído. Save acepta cualquiera de los contextos registrados. Una cadena de origen que no esté en la lista no cumple la restricción de MessageKey.

Sin entradas generadas, LingoMessages está vacío y MessageKey permite cualquier cadena. Una vez que se agregan entradas, MessageKey se convierte en la unión de sus claves de tipo cadena. El comportamiento en tiempo de ejecución no cambia: estas restricciones se aplican a l.text y l.rich durante la edición.

Mantén los tipos al día con el código fuente #

Vuelve a ejecutar la extracción después de cambiar el texto, el contexto o los marcadores de posición. Los mensajes eliminados quedan huérfanos y se excluyen de la generación. Las entradas sin contexto no aportan ninguna firma generada, a menos que otra entrada activa para la misma cadena de origen proporcione un contexto. Varios contextos para la misma cadena de origen forman una unión.

Para verificar que todo esté actualizado sin escribir archivos:

sh
npx lingo extract --src src --source-locale en --check

Esto compara tanto el JSONC como las declaraciones con la extracción actual. Es una verificación local, no una solicitud de traducción. Ejecútala junto con la verificación de tipos para evitar que una declaración desactualizada siga definiendo el inventario de mensajes de ayer sin que lo notes.

Tipos de valores y cobertura #

El generador reconoce los argumentos ICU de nivel superior. Usa number para los argumentos de plural, ordinal y número; string para los argumentos de selección; Date | number para los argumentos de fecha y hora; y string | number para los marcadores de posición simples. No detecta todos los marcadores de posición anidados dentro de una rama de plural, así que prueba explícitamente los valores de esas ramas.

Las restricciones generadas para las cadenas de origen se aplican a text y rich. Las funciones auxiliares plural y select conservan sus propias firmas de formatos y opciones. Las llamadas con contenido enriquecido agregan un mapa opcional de etiquetas, pero las declaraciones no verifican la ubicación de las etiquetas en la traducción de destino.

Los tipos te indican si una llamada cumple con el contrato de origen extraído. Las pruebas de renderizado te indican si la traducción cargada puede usar esos valores. Mantén ambas verificaciones: incluso una llamada válida puede encontrarse con una entrada ausente en el catálogo o un mensaje ICU de destino mal formado.