Osvědčené postupy

Tyto postupy vycházejí ze vzorců, které s Lingo.dev Compiler přinášejí spolehlivé a cenově efektivní výsledky. Pokrývají build pipeline, organizaci kódu, kvalitu překladu a testování.

Build pipeline#

Používejte strategii tří režimů#

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

LINGO_BUILD_MODE=translate npm run build

LINGO_BUILD_MODE=cache-only npm run build

Správa verzí#

Commitujte .lingo/ do repozitáře#

Soubor .lingo/metadata.json je jediný zdroj pravdy pro všechny překlady uložené v cache. Produkční buildy v režimu cache-only jsou na něm závislé.

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

Kontrolujte změny v překladech#

Když CI commitne aktualizované překlady, zkontrolujte diff .lingo/metadata.json v pull requestech. Díky tomu odhalíte problémy s překladem dřív, než se dostanou do produkce – podobně jako při kontrole změn v kódu.

Organizace kódu#

Vkládejte přeložitelný text přímo do JSX#

Compiler prohledává JSX a hledá přeložitelný obsah. Text uložený v JavaScriptových proměnných, konstantách nebo externích souborech neodhalí:

// 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>;
}

Ve větších codebase používejte useDirective#

Ve velkých projektech prohledávání každého souboru prodlužuje build. Aktivujte useDirective: true a přidejte 'use i18n' jen do souborů, které obsahují text viditelný pro uživatele:

{
  useDirective: true,
}

'use i18n';

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

Udržujte sourceRoot co nejužší#

Nastavte sourceRoot na nejmenší adresář, který obsahuje vaše přeložitelné komponenty. Příliš široce nastavený sourceRoot prohledává zbytečné soubory:

Kvalita překladu#

Pro výrazy značky používejte ruční přepisy#

Názvy značek, názvy produktů a právní texty by měly používat ruční přepisy, místo aby se spoléhaly na AI překlad:

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

Pro optimalizaci nákladů používejte mapování jazykových dvojic#

Různé modely mají různé silné stránky i cenové hladiny. Dražší modely přiřaďte jazykům, které je potřebují, a jinde používejte cenově efektivnější modely:

{
  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
  },
}

Pro glosář a hlas značky používejte Lingo.dev engine#

Když potřebujete v celé aplikaci konzistentní terminologii, nakonfigurujte v Lingo.dev lokalizační engine s glosářem a hlasem značky. Ty se pak automaticky použijí na každý požadavek na překlad.

Pluralizace#

Pokud ji nepotřebujete, pluralizaci vypněte#

Pokud vaše aplikace nezobrazuje vedle textu číselné hodnoty, vypněte pluralizaci a snižte složitost buildu:

{
  pluralization: { enabled: false },
}

Pište text závislý na počtu přirozeně#

Když je pluralizace aktivní, pište text s číselnými proměnnými přirozeně. Compiler se postará o převod do 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>

Testování#

Nejdřív testujte s pseudopřekladačem#

Než začnete generovat skutečné překlady, spusťte pseudopřekladač a ověřte úplné pokrytí:

1. Aktivujte dev.usePseudotranslator: true
2. Projděte každou stránku a komponentu
3. Jakýkoli text bez značek [!!! ... !!!] se nepřekládá
4. Opravte problémy s umístěním textu (přesuňte text do JSX, upravte sourceRoot, přidejte direktivy 'use i18n')

Před vydáním testujte se skutečnými překlady#

Vypněte pseudopřekladač a před vydáním vygenerujte skutečné překlady alespoň pro jeden cílový jazyk:

{
  dev: { usePseudotranslator: false },
}

Zkontrolujte přetékání rozvržení, zkracování textu a problémy s obousměrným textem, které pseudopřeklady neodhalí.

Další kroky#