Khái niệm cốt lõi

18ways có quan điểm rõ ràng về một vài điều. Khi những điều này đã rõ, phần còn lại của bề mặt API trở nên đơn giản.

Ngôn ngữ cơ sở

baseLocale của bạn là ngôn ngữ mà bạn viết bằng.

Nếu nội dung mô tả sản phẩm của bạn được viết bằng tiếng Anh Anh, thì ngôn ngữ cơ sở của bạn là en-GB. Nếu nó được viết bằng tiếng Anh Mỹ, thì ngôn ngữ cơ sở của bạn là en-US.

Khi ngôn ngữ hiện tại trùng với ngôn ngữ gốc, 18ways trả về ngay văn bản nguồn và bỏ qua công việc dịch thuật.

Ngôn ngữ đích

Ngôn ngữ đích của bạn là ngôn ngữ mà người dùng hiện đang đọc.

Trong Vanilla JS, bạn thiết lập trực tiếp nó trên engine bằng engine.setLocale(...).

Ngữ cảnh

Ngữ cảnh là cách 18ways nhóm các đoạn nội dung liên quan.

Hãy dùng chúng để giữ cho các yêu cầu dịch ngắn gọn và tránh trộn lẫn những đoạn văn bản không liên quan với nhau.

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',
});

Sử dụng tên ngữ cảnh ổn định để các nội dung liên quan luôn được nhóm lại với nhau.

Ngôn ngữ được chấp nhận

18ways phân biệt giữa:

  • một ngôn ngữ vùng mà nó có thể nhận ra, như fr-FR
  • một ngôn ngữ mà dự án của bạn thực sự chấp nhận

Trong gói lõi, bạn thường giữ danh sách ngôn ngữ được chấp nhận đó trong ứng dụng của riêng mình và chuẩn hoá trước khi gọi 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);
}

Sự kiên trì

Cookie ưu tiên ngôn ngữ được dùng bởi các bộ chuyển đổi lúc chạy là 18ways_locale.

Nếu bạn tự lưu giữ locale và muốn giữ tương thích với các lớp React hoặc Next, hãy dùng cùng một tên.

Khi bản dịch được tải

@18ways/core cung cấp cho bạn bộ máy và bộ nhớ đệm cấp thấp hơn, nhưng bạn tự chịu trách nhiệm về luồng hiển thị.

Mô hình tinh thần chung

Giữ mô hình đơn giản:

  1. Chọn gói phù hợp cho ứng dụng của bạn.
  2. Thiết lập đúng ngôn ngữ cơ sở.
  3. Giữ cho các khóa ngữ cảnh ổn định và có ý nghĩa.
  4. Hãy để runtime dịch các cụm từ hoàn chỉnh, không phải các mảnh rời.

Tiếp theo: Định dạng tin nhắn

Khái niệm cốt lõi