核心概念

18ways 對幾件事情有明確的看法。一旦這些清楚了，API 的其餘部分就會變得簡單明瞭。

基本區域

您的 baseLocale 是您所使用的語言。

如果您的產品文案是用英式英語撰寫的，則您的基本區域設置為 en-GB。如果是用美式英語撰寫的，則您的基本區域設置為 en-US。

當當前語言環境與基本語言環境匹配時，18ways 會立即返回源文本並跳過翻譯工作。

目標語言環境

您的目標語言是用戶當前正在閱讀的語言。

在 Vanilla JS 中，您可以直接使用 engine.setLocale(...) 設定引擎的語言環境。

上下文

上下文是18ways組織相關文案的方式。

使用它們來保持翻譯請求的小型化，並避免將無關的文本混合在一起。

ts
import { create18waysEngine } from '@18ways/core/engine';
 
const engine = create18waysEngine({
  apiKey: 'pk_dummy_demo_token',
  baseLocale: 'en-GB',
  locale: 'fr-FR',
  context: 'marketing',
});
 
const heroTitle = await engine.t(
  'Wrap your text. We handle the rest.',
  {
    context: 'marketing.hero',
  }
);
 
const pricingTitle = await engine.t(
  'Simple pricing',
  {
    context: 'marketing.pricing',
  }
);

使用穩定的上下文名稱，以便相關的文本保持在一起。

接受的區域設定

18ways 區分為：

  • 一個它可以識別的地區，例如 fr-FR
  • 您的專案實際接受的區域設定

在核心套件中，您通常會在自己的應用程式中保留該接受的語言列表，並在呼叫 engine.setLocale(...) 之前進行正規化。

ts
const acceptedLocales = [
  'en-GB',
  'fr-FR',
  'de-DE',
];
 
function setLocale(nextLocale: string) {
  const locale = acceptedLocales.includes(
    nextLocale
  )
    ? nextLocale
    : 'en-GB';
 
  engine.setLocale(locale);
}

堅持

運行時適配器使用的地區偏好 cookie 是 18ways_locale.

如果您堅持使用本地化並希望與 React 或 Next 層保持兼容，請使用相同的名稱。

當翻譯加載時

@18ways/core 為您提供了較低層級的引擎和快取，但您擁有渲染流程。

共享心理模型

保持模型簡單：

  1. 選擇適合您應用程式的正確套件。
  2. 正確設置基本區域設定。
  3. 保持上下文鍵穩定且有意義。
  4. 讓運行時翻譯完整的短語，而不是片段。

下一步: 訊息格式化