核心概念

18ways 对一些事情有明确的看法。一旦这些清楚了，API 的其余部分就很简单了。

基础区域

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

如果您的产品文案是用英式英语撰写的，则您的基础区域设置为 en-GB。如果是用美式英语撰写的，则您的基础区域设置为 en-US。

当当前区域设置与基础区域设置匹配时，18ways 会立即返回源文本并跳过翻译工作。

目标区域

您的目标区域是用户当前正在阅读的语言。

在 Vanilla JS 中，您可以通过 engine.setLocale(...) 直接在引擎上设置它。

上下文

上下文是18ways如何将相关的文案分组。

使用它们来保持翻译请求的小巧，并避免将无关的文本混合在一起。

ts
import { create18waysEngine } from '@18ways/core/engine';
 
const engine = create18waysEngine({
  apiKey: 'YOUR_18WAYS_PUBLIC_API_KEY',
  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. 让运行时翻译完整的短语，而不是片段。

下一步: 消息格式化

Core Concepts