Migrating from i18next to Intlayer

Tại sao nên chuyển từ i18next sang Intlayer?

Chiến lược di chuyển

Có hai chiến lược bổ sung nhau để di chuyển từ i18next sang Intlayer:

1. Compat adapter (được khuyến nghị cho các ứng dụng hiện có) — Cài đặt @intlayer/i18next. Gói này cung cấp API giống hệt với i18next nhưng ủy quyền tất cả công việc dịch cho Intlayer ở phía sau. Bạn giữ lại các lệnh gọi i18next.t(), i18next.changeLanguage() và createInstance() hiện có của mình — thay đổi duy nhất là đường dẫn import và khởi tạo.

2. Di chuyển toàn bộ — Thay thế dần các API i18next bằng các công cụ Intlayer gốc và đồng vị trí hóa nội dung trong các tệp .content.ts.

Hướng dẫn này bao gồm Chiến lược 1 trước tiên (compat adapter plug-and-play), sau đó hướng dẫn qua quá trình di chuyển toàn bộ tùy chọn.

Mục lục

Hướng dẫn sơ lược về cách chuyển đổi

Các bước sau đây là những bước tối thiểu cần thiết để chạy ứng dụng i18next hiện có của bạn trên Intlayer mà không cần thay đổi mã.

1. 1

   Cài đặt các phụ thuộc

   Cài đặt các gói Intlayer core và bộ adapter tương thích:

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   npx intlayer-cli init --interactive

   cờ --interactive là tùy chọn. Sử dụng intlayer-cli init nếu bạn là một agent AI.

   Lệnh này sẽ phát hiện môi trường của bạn và cài đặt các gói cần thiết. Ví dụ:

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   npm install intlayer @intlayer/i18next @intlayer/sync-json-plugin

   Bạn có thể giữ i18next được cài đặt — bộ adapter tương thích sử dụng nó như một devDependency / peerDependency cho các loại TypeScript.

2. 2

   Cấu hình Intlayer

   Lệnh intlayer init tạo ra một tệp intlayer.config.ts khởi động. Cập nhật nó để phù hợp với các locale hiện có của bạn và chỉ plugin syncJSON tới các tệp tin thông báo của bạn:

   intlayer.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Thêm tất cả các locale hiện có của bạn ở đây
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // khớp với cú pháp placeholder i18next: {{name}}
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   source ánh xạ một locale tới đường dẫn tệp JSON của nó. location cho Intlayer watcher biết thư mục nào để giám sát các thay đổi. Tùy chọn format: 'i18next' đảm bảo rằng các placeholder như {{name}} được phân tích cú pháp chính xác.

3. 3

   Cập nhật Alias Bundler (Tùy chọn)

   Nếu bạn đang sử dụng một bundler (Vite, Webpack, esbuild), bạn có thể tiêm một alias module sao cho import ... from 'i18next' tự động phân giải thành @intlayer/i18next. Điều này loại bỏ nhu cầu thay đổi thủ công bất kỳ import nào trong codebase của bạn.

   Cho Vite:

   vite.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { defineConfig } from "vite";
   import i18nextVitePlugin from "@intlayer/i18next/plugin";
   
   export default defineConfig({
     plugins: [i18nextVitePlugin()],
   });

   i18nextVitePlugin() bao bọc plugin intlayer() của vite-intlayer và thêm alias i18next → @intlayer/i18next cho bạn. Sử dụng plugin intlayer() đơn giản từ vite-intlayer biên dịch các từ điển nhưng không thêm alias đó — bạn sẽ cần đổi tên các import thành @intlayer/i18next theo cách thủ công (xem bước tiếp theo).

Đó là tất cả những gì bạn cần cho hướng dẫn sơ lược về cách chuyển đổi. Ứng dụng của bạn bây giờ chạy trên Intlayer trong khi giữ nguyên mọi import và API của i18next.

Hoàn thành quá trình di chuyển

Các bước dưới đây là tùy chọn và có thể được thực hiện dần dần. Chúng mở khóa bộ tính năng đầy đủ của Intlayer: trình chỉnh sửa trực quan, CMS, tệp nội dung được gõ, dịch tự động hóa bằng AI, và hơn thế nữa.

1. 4

   Đổi tên nhập rõ ràng (tùy chọn)

   Tùy chọn

   Nếu bạn muốn làm cho dependency rõ ràng trong các tệp nguồn của mình, hoặc nếu bạn không sử dụng plugin bundler để tạo alias cho các import, bạn có thể đổi tên các import theo cách thủ công:

   Hiển thị tất cả nội dung bảng

   Hiển thị tất cả nội dung bảng

   Mở bảng trong một cửa sổ bật lên để xem toàn bộ nội dung dữ liệu một cách rõ ràng

   Trước	Sau
   import i18next from 'i18next'	import i18next from '@intlayer/i18next'
   import { createInstance } from 'i18next'	import { createInstance } from '@intlayer/i18next'
   import { t } from 'i18next'	import { t } from '@intlayer/i18next'

   Đây là drop-in replacements — không cần thay đổi chữ ký hàm, đối số hoặc kiểu trả về.

2. 5

   Bật Tự động hóa Dịch được Cấp năng lượng bằng AI

   Tùy chọn

   Khi Intlayer đã được thiết lập, hãy sử dụng CLI của nó để điền các bản dịch bị thiếu một cách tự động:

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   # Kiểm tra các bản dịch bị thiếu (thêm vào CI)npx intlayer test# Điền các bản dịch bị thiếu bằng AInpx intlayer fill

   Thêm cấu hình AI vào intlayer.config.ts:

   intlayer.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // mặc định
       // model: "gpt-4o-mini",   // mặc định
     },
   };
   
   export default config;

   Xem tài liệu CLI Intlayer để biết tất cả các tùy chọn có sẵn.

Những gì bạn có thể xóa sau khi di chuyển

Khi adapter tương thích được triển khai, boilerplate i18next sau đây có thể được xóa:

Khi bạn sẵn sàng tiến thêm, Intlayer tự động phát hiện tất cả các file .content.ts và .content.json ở bất kỳ đâu trong codebase của bạn (mặc định, ở bất kỳ đâu trong ./src). Bạn có thể đặt một file my-component.content.ts ngay cạnh logic của bạn và Intlayer sẽ nhận nó tại build time mà không cần cấu hình bổ sung — không cần import, registration, hay file index tập trung. Điều này giúp việc co-locating translations hoàn toàn không gặp khó khăn.

Cấu hình TypeScript

Intlayer sử dụng module augmentation để cung cấp đầy đủ TypeScript intellisense cho các khóa dịch của bạn. Hãy đảm bảo rằng tsconfig.json của bạn bao gồm các loại được tự động tạo:

{  // ... Các cấu hình TypeScript hiện có của bạn  "include": [    // ... Các cấu hình TypeScript hiện có của bạn    ".intlayer/**/*.ts", // Bao gồm các loại được tự động tạo  ],}

Cấu hình Git

Thêm thư mục được tạo bởi Intlayer vào .gitignore của bạn:

# Bỏ qua các tệp được tạo bởi Intlayer.intlayer

Đi Xa Hơn

• Visual Editor — Quản lý bản dịch trực quan trong trình duyệt của bạn: Intlayer Visual Editor
• CMS — Ngoại hóa và quản lý nội dung từ xa: Intlayer CMS
• VS Code Extension — Nhận khả năng tự động hoàn thành và phát hiện lỗi dịch thời gian thực: Intlayer VS Code Extension
• CLI Reference — Danh sách đầy đủ các lệnh CLI: Intlayer CLI