Blog

Cómo localize.dev reescribe cadenas codificadas sin romper tu código

Lo que el motor trata como texto de UI, cómo edita un archivo sin reformatearlo, lo que se niega a adivinar y por qué una segunda ejecución no cambia nada.

Stephen Ufort · 12 de noviembre de 2026 · 5 min de lectura

Un componente antes y después de localize.dev: texto codificado reemplazado por llamadas t(), y los archivos de idioma que escribió

Pages CMS es una aplicación Next.js de código abierto sin i18n. Una ejecución de npx localize-dev run --locales es,ar,zh-CN movió 535 cadenas en 73 archivos a react-i18next: 395 claves nuevas, más 140 lugares que reutilizaron una clave porque el mismo texto ya tenía una. TypeScript compiló antes y después de la ejecución. Se omitieron dos mensajes de validación, y la solicitud de extracción los enumera con el motivo.

Solo puedes permitir que una herramienta edite 73 archivos si confías en la diferencia. Esta publicación cubre cómo el motor decide qué cambiar, cómo realiza el cambio y cuándo se detiene y te deja la decisión a ti.

Las reglas reescriben el código; un modelo nombra claves y traduce

Todo lo que toca tus archivos fuente es código determinista. El modelo tiene dos trabajos: proponer un nombre de clave como settings.notifications_heading y traducir. Nunca ve un archivo completo y nunca edita uno, por lo que no puede reformatear tu código, renombrar una variable o eliminar una importación.

Encontrar el texto que la gente ve

Cada archivo pasa por un analizador para su pila. JSX y TSX pasan por @babel/parser. Las plantillas de Vue, Svelte, Angular, Astro y Ember pasan por el compilador propio de cada framework, y el HTML plano por parse5. Las etiquetas ERB, Django y Blade se tokenizan y enmascaran primero, y la página luego pasa también por parse5. El código Swift, Dart y Android se lee con lexers más pequeños escritos a mano.

Una cadena en el árbol de sintaxis no es texto de interfaz de usuario automáticamente. La regla principal es dónde termina. Un literal cuenta cuando llega a un hijo de JSX, o a un atributo que la gente lee como placeholder, alt, title o aria-label, y puede pasar por un ternario, &&, || o paréntesis en el camino. Un nombre de clase nunca llega allí, y tampoco un argumento para console.log o para una llamada de análisis.

Este componente proviene del conjunto de pruebas del escáner. De todas las cadenas que contiene, el escáner extrae una:

test/scanner.test.ts
const A = ({ x }) => {
  console.log(`debug ${x}`);
  const label = 'Not in JSX';
  return <div className={`btn ${x}`} onClick={() => track('Clicked')}>
    <code>npm i</code><pre>raw</pre>
    <span translate="no">Brand</span>
    <div data-i18n-ignore><p>Skip me</p></div>
    <Trans>Already done</Trans>
    {t('existing.key')}
    {x ? 'primary' : 'secondary-btn'}
  </div>;
};
// extracted: ['primary']

Ambas ramas del ternario llegan a la salida, pero secondary-btn falla en un segundo conjunto de filtros que miran el valor en sí. Los identificadores snake, kebab y punteados nunca cuentan, al igual que las URL, rutas, colores, correos electrónicos, nombres de archivo, precios, versiones o listas de clases. El texto dentro de code, pre o <Trans>, o debajo de translate="no" o data-i18n-ignore, se deja solo.

Algunos textos llegan a las personas a través de código en lugar de marcado: toast(), alert(), confirm(), document.title, y mensajes de validación en esquemas zod o yup. El escáner los reconoce por la llamada a la que se pasan.

Editar sin reimprimir el archivo

La forma habitual de reescribir código es cambiar el árbol de sintaxis e imprimirlo de nuevo, lo que reformatea todo lo que la impresora toca. localize.dev nunca imprime el árbol. Toma los desplazamientos que informa el analizador y empalma cada cambio en el texto original con magic-string, por lo que cada línea que no cambia conserva su formato exacto, incluidos los comentarios.

Aquí hay un componente pequeño y lo que el motor escribe para él. Las claves aquí se nombraron sin conexión; en una ejecución real, el modelo las nombra.

src/components/Settings.tsx (before)
export function Settings({ user }) {
  return (
    <section className="settings">
      <h2>Notifications</h2>
      <p>Signed in as {user.email}</p>
      <input placeholder="Search settings" />
      <p>Read the <a href="/help">help center</a> before you change these.</p>
    </section>
  );
}
src/components/Settings.tsx (after)
import { useTranslation, Trans } from 'react-i18next';

export function Settings({ user }) {
  const { t } = useTranslation();
  return (
    <section className="settings">
      <h2>{t('settings.notifications')}</h2>
      <p>{t('settings.signed_in_as', { email: user.email })}</p>
      <input placeholder={t('settings.search_settings')} />
      <p><Trans i18nKey="settings.read_the_help_center_before" components={{ a: <a href="/help" /> }} /></p>
    </section>
  );
}

{user.email} se convirtió en un valor con nombre, por lo que los traductores ven Signed in as {{email}} y pueden moverlo. La oración con el enlace permaneció completa como un solo mensaje <Trans>, porque un traductor necesita la oración completa para colocar el enlace en el lugar correcto.

Poner t en el ámbito sigue al código que ya está allí. Se reutiliza una const { t } = useTranslation() existente en la función. De lo contrario, la línea del hook va antes de la primera declaración, y se abre un cuerpo de flecha corto para dejar espacio para ella. Los componentes del servidor de Next.js obtienen await getTranslation() y se convierten en async; los componentes de clase obtienen withTranslation(). La importación va después de tu última importación, y solo si falta.

Cuando no adivina

Algunas cadenas no se pueden reescribir de forma segura. Estas se omiten y se enumeran con un motivo. Un mensaje en un esquema creado fuera de cualquier componente no tiene t para llamar en ese punto, razón por la cual se omitieron las dos cadenas de Pages CMS. Otras razones incluyen una t que ya significa algo más en ese ámbito, y una constante que se exporta o se lee en más de un componente, donde cambiarla podría afectar a los otros lectores.

Las cadenas omitidas aparecen en la solicitud de extracción en "Cadenas omitidas", y localize-dev check sigue informándolas hasta que alguien las mueva.

Ejecutarlo dos veces no cambia nada

Después de una ejecución, el texto es t('key'). Una cadena pasada a t() no llega a la salida como un literal, por lo que el escáner no la vuelve a capturar. El pipeline solo pone en cola las cadenas que no tienen clave, o las claves a las que les falta una traducción, y los archivos cuyo contenido resultó ser el mismo se dejan fuera del resultado. El conjunto de pruebas ejecuta el motor en su propia salida y espera que no haya cambios.

Comprobando traducciones antes de que se escriban

Cada traducción se verifica con su fuente: marcadores de posición, etiquetas de marcado y cada forma plural que el idioma necesita, que son seis para árabe y una para japonés. Se le pide una vez más a una traducción que falla con el motivo adjunto. Si vuelve a fallar, se omite y se informa, nunca se escribe. Una publicación separada cubre eso en detalle.

Lo que sale de tu máquina

El análisis y la reescritura se ejecutan en su máquina o en su ejecutor de CI. Para cada cadena, el modelo recibe el texto con sus marcadores de posición, la ruta del archivo y una pista corta como "placeholder" attribute on <input> in component <Login>. No recibe su código fuente. Las ejecuciones de check, scan y --offline no envían nada.

Lo que no hace

  • La salida de React y Next.js es react-i18next. Si tu aplicación ya usa react-intl, next-intl o Lingui, localize.dev no escribirá en ellas.
  • Swift, Dart y Android se leen con lexers, no con sus compiladores.
  • Las cadenas que no puede colocar se enumeran y moverlas depende de usted.

Si se equivocó con tu código, me gustaría ver el archivo. El playground ejecuta este motor en el código que pegas, sin cuenta.

Pruébalo en tu propio código en la zona de juegos, no se necesita cuenta