Best Practices

Diese Best Practices basieren auf Mustern, die mit dem Lingo.dev Compiler zuverlässige und kosteneffiziente Ergebnisse liefern. Sie decken die Build-Pipeline, die Code-Organisation, die Übersetzungsqualität und das Testen ab.

Build-Pipeline#

Nutzen Sie die Drei-Modi-Strategie#

{
  buildMode: "translate",
  dev: { usePseudotranslator: true },
}

LINGO_BUILD_MODE=translate npm run build

LINGO_BUILD_MODE=cache-only npm run build

Versionskontrolle#

Committen Sie .lingo/ in Ihr Repository#

Die Datei .lingo/metadata.json ist die zentrale Quelle für alle zwischengespeicherten Übersetzungen. Produktions-Builds im Modus cache-only hängen davon ab.

# .gitignore - do NOT ignore .lingo/
node_modules/
dist/
.env

Prüfen Sie Übersetzungs-Diffs#

Wenn CI aktualisierte Übersetzungen committet, prüfen Sie den Diff von .lingo/metadata.json in Pull Requests. So können Sie Übersetzungsprobleme erkennen, bevor sie in die Produktion gelangen – ähnlich wie bei Codeänderungen.

Code-Organisation#

Platzieren Sie übersetzbaren Text direkt in JSX#

Der Compiler scannt JSX nach übersetzbaren Inhalten. Text, der in JavaScript-Variablen, Konstanten oder externen Dateien gespeichert ist, wird nicht erkannt:

// Good - compiler detects this text
export function Header() {
  return <h1>Welcome to our app</h1>;
}

// Bad - compiler cannot detect text in a variable
const title = "Welcome to our app";
export function Header() {
  return <h1>{title}</h1>;
}

Verwenden Sie useDirective für große Codebasen#

In großen Projekten erhöht das Scannen jeder Datei die Build-Zeit. Aktivieren Sie useDirective: true und fügen Sie 'use i18n' nur in Dateien ein, die nutzerseitigen Text enthalten:

{
  useDirective: true,
}

'use i18n';

// Only this file is scanned for translations
export function PublicPage() {
  return <h1>Welcome</h1>;
}

Halten Sie sourceRoot möglichst eng#

Setzen Sie sourceRoot auf das kleinste Verzeichnis, das Ihre übersetzbaren Komponenten enthält. Ein zu breit gefasstes sourceRoot scannt unnötige Dateien:

Übersetzungsqualität#

Verwenden Sie manuelle Overrides für Markenbegriffe#

Markennamen, Produktnamen und Rechtstexte sollten mit manual overrides gesteuert werden, statt sich auf KI-Übersetzung zu verlassen:

<h1 data-lingo-override={{ es: "Motor de Localizacion", de: "Lokalisierungs-Engine" }}>
  Localization Engine
</h1>

Nutzen Sie Sprache-Paar-Mapping zur Kostenoptimierung#

Unterschiedliche Modelle haben unterschiedliche Stärken und Preisniveaus. Ordnen Sie teure Modelle den Sprachen zu, die sie brauchen, und setzen Sie in anderen Fällen kosteneffiziente Modelle ein:

{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",      // Fast, cost-effective default
    "*:ja": "anthropic:claude-3-5-sonnet",       // Higher quality for Japanese
    "*:zh-Hans": "anthropic:claude-3-5-sonnet",  // Higher quality for Chinese
  },
}

Verwenden Sie die Lingo.dev Engine für Glossar und Markenstimme#

Wenn Sie in Ihrer App eine konsistente Terminologie benötigen, konfigurieren Sie auf Lingo.dev eine Lokalisierungs-Engine mit einem Glossar und einer Markenstimme. Diese werden automatisch auf jede Übersetzungsanfrage angewendet.

Pluralisierung#

Deaktivieren Sie die Pluralisierung, wenn Sie sie nicht brauchen#

Wenn Ihre App keine numerischen Werte zusammen mit Text anzeigt, deaktivieren Sie die Pluralisierung, um die Build-Komplexität zu reduzieren:

{
  pluralization: { enabled: false },
}

Formulieren Sie anzahlabhängigen Text natürlich#

Wenn die Pluralisierung aktiviert ist, formulieren Sie Text mit numerischen Variablen natürlich. Der Compiler übernimmt die Konvertierung in ICU MessageFormat:

// Good - the compiler detects and pluralizes this
<p>You have {count} items in your cart</p>

// Also good - works with any numeric expression
<p>{unreadCount} unread messages</p>

Tests#

Testen Sie zuerst mit dem Pseudotranslator#

Bevor Sie echte Übersetzungen generieren, führen Sie den Pseudotranslator aus, um die vollständige Abdeckung zu prüfen:

1. Aktivieren Sie dev.usePseudotranslator: true
2. Navigieren Sie durch jede Seite und jede Komponente
3. Jeder Text ohne [!!! ... !!!]-Marker wird nicht übersetzt
4. Beheben Sie Probleme bei der Textplatzierung (verschieben Sie Text in JSX, passen Sie sourceRoot an, fügen Sie 'use i18n'-Direktiven hinzu)

Testen Sie vor dem Release mit echten Übersetzungen#

Deaktivieren Sie den Pseudotranslator und generieren Sie vor dem Release echte Übersetzungen für mindestens eine Zielsprache:

{
  dev: { usePseudotranslator: false },
}

Prüfen Sie auf Layout-Überlauf, abgeschnittenen Text und bidirektionale Textprobleme, die Pseudoübersetzungen nicht sichtbar machen können.

Nächste Schritte#