Comprueba los tipos de las llamadas a mensajes

Genera e incluye declaraciones que comprueben 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 aparezca el texto de origen o {name} 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. Añade lingo.d.ts a la lista de inclusión existente en tsconfig 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 comprobación de tipos habitual de la aplicación. Una declaración que quede fuera del proyecto del compilador no impone restricciones a ninguna llamada. Si la extracción utiliza --types o i18n.typesPath, incluye en su lugar la ruta de salida correspondiente.

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 a mano. El saludo ahora requiere values.name y el contexto extraído. Save acepta cualquiera de los contextos registrados. Una cadena de origen que no figure en la lista incumple la restricción de MessageKey.

Sin entradas generadas, LingoMessages está vacío y MessageKey permite cualquier cadena. Una vez que contiene entradas, MessageKey pasa a ser 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 texto de origen #

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, salvo que otra entrada activa de la misma cadena de origen proporcione un contexto. Los distintos contextos de una misma cadena de origen forman una unión.

Para comprobar que los archivos están al día sin escribirlos:

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

Esta comprobación compara tanto el JSONC como las declaraciones con la extracción actual. Es una comprobación local, no una solicitud de traducción. Ejecútala junto con la comprobación de tipos para evitar que una declaración antigua siga definiendo un inventario de mensajes desactualizado sin que te des cuenta.

Tipos de valores y cobertura #

El generador reconoce los argumentos ICU de nivel superior. Utiliza 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 expresamente 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 formas y opciones. Las llamadas con contenido enriquecido añaden un mapa de etiquetas opcional, pero las declaraciones no comprueban dónde se sitúan las etiquetas en la traducción.

Los tipos te indican si una llamada se ajusta al contrato del mensaje de origen extraído. Las pruebas de renderizado te indican si la traducción cargada puede utilizar esos valores. Mantén ambas comprobaciones: incluso una llamada válida puede encontrarse con una entrada que falte en el catálogo o con un ICU mal formado en la traducción.