Migrating from vue-i18n to Intlayer

Tại sao nên chuyển từ vue-i18n sang Intlayer?

Chiến lược di chuyển

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

1. Compat adapter (được khuyến nghị cho các ứng dụng hiện có) — Cài đặt @intlayer/vue-i18n (cho các Vue component). Package này cung cấp cùng API như vue-i18n nhưng ủy thác 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 $t, useI18n(), và <i18n-t> hiện có — thay đổi duy nhất là đường dẫn import và khởi tạo.

2. Di chuyển toàn bộ — Dần dần thay thế các API của vue-i18n bằng các Intlayer hook gốc (useIntlayer) và đặt cùng vị trí nội dung trong các tệp .content.ts bên cạnh các component của bạn.

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

Mục lục

Hướng dẫn di chuyển nhanh chóng

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

1. 1

   Cài đặt Dependencies

   Cài đặt các gói core của Intlayer và 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 AI agent.

   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 vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin

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

2. 2

   Cấu hình Intlayer

   Lệnh intlayer init tạo một intlayer.config.ts khởi động. Cập nhật nó để khớp với các locale hiện tại của bạn và trỏ plugin syncJSON vào các tệp tin message 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 tại của bạn ở đây
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // khớp với cú pháp placeholder vue-i18n: {name}
         format: "icu",
         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 để theo dõi các thay đổi. Tùy chọn format: 'icu' đảm bảo rằng các placeholder được phân tích cú pháp chính xác cho vue-i18n.

3. 3

   Thêm plugin Intlayer vào Bundler của bạn

   Bao bọc cấu hình bundler hiện tại của bạn bằng plugin tương thích. Nó sáng tác plugin core Intlayer, thiết lập content watching, và — quan trọng nhất — chèn một module alias để các lệnh gọi import … from 'vue-i18n' hiện tại của bạn được chuyển hướng trong suốt tới @intlayer/vue-i18n tại thời gian xây dựng. Không cần thay đổi tệp source.

   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 vue from "@vitejs/plugin-vue";
   import { vueI18nVitePlugin } from "@intlayer/vue-i18n/plugin";
   
   export default defineConfig({
     plugins: [vue(), vueI18nVitePlugin()],
   });

   vueI18nVitePlugin() bao bọc plugin intlayer() của vite-intlayer và thêm alias vue-i18n. Sử dụng plugin intlayer() đơn thuần từ vite-intlayer biên dịch dictionaries nhưng không thêm alias — sau đó bạn sẽ cần đổi tên imports thành @intlayer/vue-i18n theo cách thủ công (xem Bước 4).

   Cho Nuxt:

   Nếu bạn đang sử dụng @nuxtjs/i18n (tích hợp Nuxt), cài đặt nuxt-intlayer và thêm nó vào nuxt.config.ts của bạn:

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   npm install nuxt-intlayer

   nuxt.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   export default defineNuxtConfig({
     modules: ["nuxt-intlayer"],
     // Bạn có thể an toàn loại bỏ @nuxtjs/i18n từ các module của bạn
   });

   Bạn không còn cần createI18n() hoặc bootstrap provider thủ công. Intlayer biên dịch tất cả dictionaries tại thời gian xây dựng, vì vậy không có bước tải thời gian chạy. Provider được tạo alias xử lý khởi tạo cho bạn.

Đó là tất cả những gì cần thiết cho hướng dẫn di chuyển nhanh chóng. Ứng dụng của bạn giờ đây chạy trên Intlayer trong khi giữ nguyên mọi lệnh gọi và API vue-i18n.

Các khóa dịch được gõ — tự động. Sau khi Intlayer biên dịch các dictionaries của bạn, useI18n được gõ đối với nội dung thực tế của bạn khi bạn chuyển tùy chọn namespace. Các khóa được tự động hoàn thành trong IDE của bạn và các đường dẫn không hợp lệ gây ra các lỗi TypeScript tại thời gian xây dựng — không cần thiết lập bổ sung.

ts

Sao chép nội dung

Sao chép mã

Sao chép mã vào clipboard

// 'about' là một khóa dictionary được đăng kýconst { t } = useI18n({ namespace: "about" });t("counter.label"); // ✓ tự động hoàn thànht("does.not.exist"); // ✗ Lỗi TypeScript

Hoàn tất quá trình di chuyển

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

1. 4

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

   Tùy chọn

   Các plugin Intlayer đã xử lý aliasing ở cấp bundler. Nếu bạn muốn làm cho phụ thuộc rõ ràng trong các tệp nguồn của mình, 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 { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'
   import { createI18n } from 'vue-i18n'	import { createI18n } from '@intlayer/vue-i18n'

   Đây là các thay thế drop-in — không cần thay đổi nào đối với chữ ký cuộc gọi, đối số hoặc các loại trả về.

2. 5

   Bật Tự động hóa Dịch được Hỗ trợ bởi AI

   Tùy chọn

   Sau khi Intlayer được kết nối, hãy sử dụng CLI của nó để điền các bản dịch còn thiếu 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 còn thiếu (thêm vào CI)npx intlayer test# Điền các bản dịch còn 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: "icu",
         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 Intlayer CLI để 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

Sau khi các bộ chuyển đổi tương thích được đặt vào, các boilerplate vue-i18n sau đây có thể bị xóa:

Khi bạn sẵn sàng để đi xa hơn, 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 (theo mặc định, ở bất kỳ đâu bên trong ./src). Bạn có thể đặt một file my-component.content.ts ngay cạnh MyComponent.vue của bạn và Intlayer sẽ nhận nó tại thời điểm build mà không cần cấu hình bổ sung — không imports, không registration, không file index tập trung. Điều này làm cho việc đặt cùng vị trí translations với pages và components hoàn toàn không gây 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. Đả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 Sâu Hơn

• Visual Editor — Quản lý bản dịch một cách trực quan trong trình duyệt của bạn: Intlayer Visual Editor
• CMS — Quản lý nội dung từ xa: Intlayer CMS
• VS Code Extension — Nhận khuyến nghị tự động hoàn thành mã và phát hiện lỗi dịch theo thời gian thực: Intlayer VS Code Extension
• CLI Reference — Danh sách đầy đủ các lệnh CLI: Intlayer CLI
• Intlayer with Vue — Hướng dẫn thiết lập hoàn chỉnh cho Vue: intlayerwithvite+vue.md
• Intlayer with Nuxt — Hướng dẫn thiết lập hoàn chỉnh cho Nuxt: intlayerwithnuxt.md