Blog

Comment localize.dev réécrit les chaînes codées en dur sans casser votre code

Ce que le moteur traite comme du texte d'interface utilisateur, comment il modifie un fichier sans le reformater, ce qu'il refuse de deviner, et pourquoi une seconde exécution ne change rien.

Stephen Ufort · 12 novembre 2026 · 5 min de lecture

Un composant avant et après localize.dev : texte codé remplacé par des appels t(), et les fichiers de langue qu'il a écrits

Pages CMS est une application Next.js open-source sans i18n. Une exécution de npx localize-dev run --locales es,ar,zh-CN a déplacé 535 chaînes dans 73 fichiers vers react-i18next : 395 nouvelles clés, plus 140 emplacements qui ont réutilisé une clé car le même texte en avait déjà une. TypeScript a compilé avant et après l'exécution. Deux messages de validation ont été ignorés, et la pull request les liste avec la raison.

Vous ne pouvez autoriser un outil à modifier que 73 fichiers si vous faites confiance à la différence. Cet article explique comment le moteur décide de ce qu'il faut changer, comment il effectue le changement, et quand il s'arrête et vous laisse la décision.

Les règles réécrivent le code ; un modèle nomme les clés et traduit

Tout ce qui touche à vos fichiers source est du code déterministe. Le modèle a deux tâches : proposer un nom de clé tel que settings.notifications_heading et traduire. Il ne voit jamais un fichier entier et n'en modifie jamais un, il ne peut donc pas reformater votre code, renommer une variable ou supprimer une importation.

Trouver le texte que les gens voient

Chaque fichier passe par un analyseur pour sa pile. JSX et TSX passent par @babel/parser. Les modèles Vue, Svelte, Angular, Astro et Ember passent par le propre compilateur de chaque framework, et le HTML brut par parse5. Les balises ERB, Django et Blade sont d'abord tokenisées et masquées, puis la page passe également par parse5. Le code Swift, Dart et Android est lu avec des analyseurs lexicaux plus petits écrits à la main.

Une chaîne dans l'arbre syntaxique n'est pas automatiquement du texte d'interface utilisateur. La règle principale concerne l'endroit où elle aboutit. Un littéral compte lorsqu'il atteint un enfant JSX, ou un attribut que les gens lisent tel que placeholder, alt, title ou aria-label, et il peut passer par un opérateur ternaire, &&, || ou des parenthèses en cours de route. Un nom de classe n'y parvient jamais, pas plus qu'un argument pour console.log ou pour un appel d'analyse.

Ce composant provient de la suite de tests du scanner. Parmi toutes les chaînes qu'il contient, le scanner en extrait une :

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']

Les deux branches de l'opérateur ternaire atteignent la sortie, mais secondary-btn échoue à un deuxième ensemble de filtres qui examinent la valeur elle-même. Les identifiants snake, kebab et dotted ne comptent jamais, pas plus que les URL, les chemins, les couleurs, les e-mails, les noms de fichiers, les prix, les versions ou les listes de classes. Le texte à l'intérieur de code, pre ou <Trans>, ou sous translate="no" ou data-i18n-ignore, est laissé tel quel.

Certains textes parviennent aux utilisateurs via le code plutôt que par le balisage : toast(), alert(), confirm(), document.title, et les messages de validation dans les schémas zod ou yup. Le scanner les reconnaît par l'appel auquel ils sont passés.

Modifier sans réimprimer le fichier

La façon habituelle de réécrire du code est de modifier l'arbre syntaxique et de l'imprimer à nouveau, ce qui reformatte tout ce que l'imprimante touche. localize.dev n'imprime jamais l'arbre. Il prend les décalages signalés par l'analyseur et insère chaque modification dans le texte original avec magic-string, de sorte que chaque ligne qu'il ne modifie pas conserve son formatage exact, commentaires inclus.

Voici un petit composant et ce que le moteur écrit pour lui. Les clés ont été nommées hors ligne ; lors d'une exécution réelle, le modèle les nomme.

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} est devenu une valeur nommée, les traducteurs voient donc Signed in as {{email}} et peuvent le déplacer. La phrase avec le lien est restée entière comme un seul message <Trans>, car un traducteur a besoin de la phrase complète pour placer le lien au bon endroit.

Mettre t dans la portée suit le code qui est déjà là. Une const { t } = useTranslation() existante dans la fonction est réutilisée. Sinon, la ligne du hook va avant la première instruction, et un corps de flèche court est ouvert pour y faire de la place. Les composants serveur Next.js obtiennent await getTranslation() et deviennent async ; les composants de classe obtiennent withTranslation(). L'importation se fait après votre dernière importation, et seulement si elle manque.

Quand il ne devine pas

Certaines chaînes ne peuvent pas être réécrites en toute sécurité. Celles-ci sont ignorées et répertoriées avec une raison. Un message dans un schéma construit en dehors de tout composant n'a pas de t à appeler à ce stade, c'est pourquoi les deux chaînes CMS Pages ont été ignorées. D'autres raisons incluent une t qui signifie déjà autre chose dans cette portée, et une constante qui est exportée ou lue par plus d'un composant, où sa modification pourrait affecter les autres lecteurs.

Les chaînes ignorées apparaissent dans la pull request sous « Chaînes ignorées », et localize-dev check continue de les signaler jusqu'à ce que quelqu'un les déplace.

Le lancer deux fois ne change rien

Après une exécution, le texte est t('key'). Une chaîne passée à t() n'atteint pas la sortie en tant que littéral, le scanner ne la capture donc pas à nouveau. Le pipeline met en file d'attente uniquement les chaînes qui n'ont pas de clé, ou les clés auxquelles il manque une traduction, et les fichiers dont le contenu est resté le même sont exclus du résultat. La suite de tests exécute le moteur sur sa propre sortie et n'attend aucun changement.

Vérifier les traductions avant qu'elles ne soient écrites

Chaque traduction est vérifiée par rapport à sa source : espaces réservés, balises de balisage et chaque forme plurielle dont la langue a besoin, soit six pour l'arabe et une pour le japonais. Une traduction qui échoue est demandée une fois de plus avec la raison jointe. Si elle échoue à nouveau, elle est omise et signalée, jamais écrite. Un article séparé couvre cela en détail.

Ce qui quitte votre machine

L'analyse et la réécriture s'exécutent sur votre machine ou votre exécuteur CI. Pour chaque chaîne, le modèle reçoit le texte avec ses espaces réservés, le chemin du fichier et un bref indice tel que "placeholder" attribute on <input> in component <Login>. Il n'obtient pas votre code source. Les exécutions de check, scan et --offline n'envoient rien.

Ce qu'il ne fait pas

  • La sortie de React et Next.js est react-i18next. Si votre application utilise déjà react-intl, next-intl ou Lingui, localize.dev n'écrira pas dedans.
  • Swift, Dart et Android sont lus avec des analyseurs lexicaux (lexers), pas leurs compilateurs.
  • Les chaînes qu'il ne peut pas placer sont listées, et leur déplacement vous appartient.

S'il s'est trompé dans votre code, j'aimerais voir le fichier. Le terrain de jeu exécute ce moteur sur le code que vous collez, sans compte.

Essayez-le sur votre propre code dans le terrain de jeu, aucun compte requis