Blog

Wie localize.dev hartcodierte Strings umschreibt, ohne Ihren Code zu beschädigen

Was die Engine als UI-Text behandelt, wie sie eine Datei bearbeitet, ohne sie neu zu formatieren, was sie nicht zu erraten versucht und warum ein zweiter Durchlauf nichts ändert.

Stephen Ufort · 12. November 2026 · 5 Min. Lesezeit

Eine Komponente vor und nach localize.dev: hartcodierter Text ersetzt durch t()-Aufrufe und die von ihm geschriebenen Sprachdateien

Pages CMS ist eine Open-Source-Next.js-App ohne i18n. Ein Durchlauf von npx localize-dev run --locales es,ar,zh-CN verschob 535 Strings in 73 Dateien nach react-i18next: 395 neue Schlüssel, plus 140 Stellen, die einen Schlüssel wiederverwendeten, weil derselbe Text bereits einen hatte. TypeScript wurde vor und nach dem Lauf kompiliert. Zwei Validierungsmeldungen wurden übersprungen, und die Pull-Anfrage listet sie mit dem Grund auf.

Sie können einem Tool nur erlauben, 73 Dateien zu bearbeiten, wenn Sie dem Diff vertrauen können. Dieser Beitrag behandelt, wie die Engine entscheidet, was geändert werden soll, wie sie die Änderung vornimmt und wann sie stoppt und Ihnen die Entscheidung überlässt.

Regeln schreiben den Code neu; ein Modell benennt Schlüssel und übersetzt

Alles, was Ihre Quelldateien berührt, ist deterministischer Code. Das Modell hat zwei Aufgaben: einen Schlüsselnamen wie settings.notifications_heading vorschlagen und übersetzen. Es sieht nie eine ganze Datei und bearbeitet nie eine, daher kann es Ihren Code nicht neu formatieren, eine Variable umbenennen oder einen Import fallen lassen.

Den Text finden, den die Leute sehen

Jede Datei durchläuft einen Parser für ihren Stack. JSX und TSX durchlaufen @babel/parser. Vue-, Svelte-, Angular-, Astro- und Ember-Vorlagen durchlaufen den eigenen Compiler jedes Frameworks, und einfaches HTML durchläuft parse5. ERB-, Django- und Blade-Tags werden zuerst tokenisiert und maskiert, und die Seite durchläuft dann ebenfalls parse5. Swift-, Dart- und Android-Code werden mit kleineren handgeschriebenen Lexern gelesen.

Ein String im Syntaxbaum ist nicht automatisch UI-Text. Die Hauptregel ist, wo er endet. Ein Literal zählt, wenn es ein JSX-Kind erreicht, oder ein Attribut, das Leute lesen, wie placeholder, alt, title oder aria-label, und es kann auf dem Weg durch ein Ternary, &&, || oder Klammern gehen. Ein Klassenname erreicht niemals dort, und auch kein Argument für console.log oder für einen Analyseaufruf.

Diese Komponente stammt aus der Testsuite des Scanners. Von allen darin enthaltenen Zeichenfolgen extrahiert der Scanner eine:

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

Beide Zweige des Ternary erreichen die Ausgabe, aber secondary-btn schlägt einen zweiten Satz von Filtern fehl, die den Wert selbst betrachten. Snake-, Kebab- und gepunktete IDs zählen nie, ebenso wenig wie URLs, Pfade, Farben, E-Mails, Dateinamen, Preise, Versionen oder Klassenlisten. Text innerhalb von code, pre oder <Trans>, oder unter translate="no" oder data-i18n-ignore, bleibt unberührt.

Einige Texte erreichen die Benutzer über Code anstelle von Markup: toast(), alert(), confirm(), document.title und Validierungsnachrichten in Zod- oder Yup-Schemas. Der Scanner erkennt diese anhand des Aufrufs, an den sie übergeben werden.

Bearbeiten ohne Nachdruck der Datei

Der übliche Weg, Code neu zu schreiben, besteht darin, den Syntaxbaum zu ändern und ihn erneut zu drucken, was alles neu formatiert, was der Drucker berührt. localize.dev druckt den Baum nie. Es nimmt die Offsets, die der Parser meldet, und fügt jede Änderung in den Originaltext mit magic-string ein, sodass jede Zeile, die es nicht ändert, seine exakte Formatierung beibehält, einschließlich Kommentaren.

Hier ist eine kleine Komponente und was die Engine dafür schreibt. Die Schlüssel hier wurden offline benannt; in einem echten Durchlauf benennt das Modell sie.

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} wurde zu einem benannten Wert, sodass Übersetzer Signed in as {{email}} sehen und ihn verschieben können. Der Satz mit dem Link blieb als eine <Trans>-Nachricht erhalten, da ein Übersetzer den vollständigen Satz benötigt, um den Link an der richtigen Stelle zu platzieren.

Das Einbringen von t in den Gültigkeitsbereich folgt dem bereits vorhandenen Code. Eine vorhandene const { t } = useTranslation() in der Funktion wird wiederverwendet. Andernfalls geht die Hook-Zeile vor der ersten Anweisung, und ein kurzer Pfeilkörper wird geöffnet, um Platz dafür zu schaffen. Next.js-Serverkomponenten erhalten await getTranslation() und werden zu async; Klassenkomponenten erhalten withTranslation(). Der Import erfolgt nach Ihrem letzten Import, und nur, wenn er fehlt.

Wenn es nicht errät

Einige Zeichenfolgen können nicht sicher neu geschrieben werden. Diese werden übersprungen und mit einem Grund aufgelistet. Eine Nachricht in einem Schema, das außerhalb einer Komponente erstellt wurde, hat zu diesem Zeitpunkt keine t zum Aufrufen, weshalb die beiden Pages CMS-Zeichenfolgen übersprungen wurden. Andere Gründe sind eine t, die in diesem Bereich bereits etwas anderes bedeutet, und eine Konstante, die exportiert oder von mehr als einer Komponente gelesen wird, wobei eine Änderung die anderen Leser stören könnte.

Übersprungene Zeichenfolgen erscheinen in der Pull-Anforderung unter „Übersprungene Zeichenfolgen“, und localize-dev check meldet sie weiterhin, bis jemand sie verschiebt.

Zweimaliges Ausführen ändert nichts

Nach einem Durchlauf ist der Text t('key'). Eine an t() übergebene Zeichenfolge erreicht die Ausgabe nicht als Literal, sodass der Scanner sie nicht erneut erfasst. Die Pipeline reiht nur Zeichenfolgen in die Warteschlange, die keinen Schlüssel haben oder bei denen ein Schlüssel eine Übersetzung vermissen lässt, und Dateien, deren Inhalt gleich geblieben ist, werden vom Ergebnis ausgeschlossen. Die Testsuite führt die Engine auf ihrer eigenen Ausgabe aus und erwartet keine Änderungen.

Übersetzungen prüfen, bevor sie geschrieben werden

Jede Übersetzung wird mit ihrer Quelle abgeglichen: Platzhalter, Markup-Tags und jede Pluralform, die die Sprache benötigt, sechs für Arabisch und eine für Japanisch. Eine fehlgeschlagene Übersetzung wird mit dem angehängten Grund noch einmal angefordert. Wenn sie erneut fehlschlägt, wird sie weggelassen und gemeldet, niemals geschrieben. Ein separater Beitrag behandelt dies im Detail.

Was Ihren Computer verlässt

Parsing und Rewriting laufen auf Ihrem Rechner oder Ihrem CI-Runner. Für jede Zeichenkette erhält das Modell den Text mit seinen Platzhaltern, den Dateipfad und einen kurzen Hinweis wie "placeholder" attribute on <input> in component <Login>. Es erhält nicht Ihren Quellcode. check, scan und --offline Läufe senden nichts.

Was es nicht tut

  • Die Ausgabe von React und Next.js ist react-i18next. Wenn Ihre App bereits react-intl, next-intl oder Lingui verwendet, schreibt localize.dev nicht dorthin.
  • Swift, Dart und Android werden mit Lexern gelesen, nicht mit ihren Compilern.
  • Zeichenketten, die es nicht platzieren kann, werden aufgelistet, und das Verschieben liegt bei Ihnen.

Wenn es Ihren Code falsch verstanden hat, würde ich die Datei gerne sehen. Die Playground-Umgebung führt diese Engine auf Code aus, den Sie einfügen, ohne Konto.

Probieren Sie es mit Ihrem eigenen Code im Playground aus, kein Konto erforderlich