Migrating từ @nuxtjs/i18n to Intlayer

Tại sao nên chuyển đổi từ @nuxtjs/i18n sang Intlayer?

Chiến lược di chuyển

Vì @nuxtjs/i18n được hỗ trợ bởi vue-i18n ở phía dưới, có hai chiến lược bổ sung cho việc di chuyển sang Intlayer:

1. Compat adapter (khuyến nghị cho các ứng dụng hiện có) — Cài đặt @intlayer/vue-i18n và nuxt-intlayer. Điều này cung cấp cùng API chính xác như vue-i18n nhưng ủy quyền tất cả công việc dịch thuật cho Intlayer ở phía dưới. Bạn giữ lại $t, useI18n(), và định tuyến Nuxt hiện có — thay đổi duy nhất là khởi tạo.

2. Di chuyển đầy đủ — Từng bước thay thế các API @nuxtjs/i18n bằng các hook Intlayer gốc (useIntlayer) và đặt cùng vị trí nội dung trong các file .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 (compat adapter drop-in), sau đó hướng dẫn qua di chuyển đầy đủ tùy chọn.

Mục lục

Quá trình di chuyển nhanh

Các bước sau là mức tối thiểu cần thiết để chạy ứng dụng Nuxt hiện có của bạn trên Intlayer mà không cần thay đổi bất kỳ mã nào trong các thành phần của bạn.

1. 1

   Cài đặt Phụ thuộc

   Cài đặt các gói lõi 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 tác nhân 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 vue-intlayer nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin

   Bạn có thể an toàn giữ @nuxtjs/i18n được cài đặt trong quá trình di chuyển, mặc dù bạn sẽ xóa nó khỏi cấu hình Nuxt của mình sớm.

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ó để phù hợp với các locale hiện có của bạn và chỉ plugin syncJSON vào các tệp tin nhắn 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 vue-i18n: {name}
         format: "icu",
         source: ({ locale }) => `./locales/${locale}.json`,
         location: "locales",
       }),
     ],
   };
   
   export default config;

   source ánh xạ một locale vào đường dẫn tệp JSON của nó. location cho trình quan sát Intlayer biết thư mục nào để giám sát những thay đổi. Tùy chọn format: 'icu' đảm bảo rằng các placeholder được phân tích chính xác cho vue-i18n.

3. 3

   Cập nhật Cấu hình Nuxt

   Thay thế module @nuxtjs/i18n bằng nuxt-intlayer trong nuxt.config.ts của bạn. Plugin Intlayer tự động cài đặt các alias module, có nghĩa là các cuộc gọi import { useI18n } from 'vue-i18n' hiện có của bạn được chuyển hướng trong suốt sang @intlayer/vue-i18n.

   nuxt.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   export default defineNuxtConfig({
     // Xóa '@nuxtjs/i18n'
     modules: ["nuxt-intlayer"],
   });

   Bạn không cần định nghĩa các đối tượng cấu hình i18n Nuxt nữa. Intlayer biên dịch tất cả các từ điển vào thời gian xây dựng, xử lý phát hiện locale, định tuyến và tải từ điển một cách liền mạch.

Đó là tất cả những gì cần thiết cho quá trình di chuyển nhanh. Ứng dụng Nuxt của bạn hiện chạy trên Intlayer trong khi giữ lại mọi $t và useI18n().

Hoàn tất 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 Intlayer đầy đủ: 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à hơn thế nữa.

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'

   Đây là những thay thế trực tiếp — không cần thay đổi gì về chữ ký cuộc gọi, đối số hoặc kiểu trả về.

2. 5

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

   Tùy chọn

   Khi Intlayer được kết nối, hãy sử dụng CLI của nó để điền vào các bản dịch bị 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 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: "icu",
         source: ({ locale }) => `./locales/${locale}.json`,
         location: "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

Khi compat adapter đã được triển khai, boilerplate sau đây có thể được 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 bên cạnh MyComponent.vue của bạn và Intlayer sẽ nhận nó tại thời gian build mà không cần bất kỳ cấu hình bổ sung nào — không có imports, không có registration, không cần file index tập trung. Điều này làm cho việc đặt các bản dịch cùng với các trang và thành phần hoàn toàn không ma sát.

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 tsconfig.json của bạn bao gồm các kiểu đượ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 kiểu đượ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 — Externalize và quản lý nội dung từ xa: Intlayer CMS
• VS Code Extension — Nhận autocompletion và phát hiện lỗi bản dịch real-time: Intlayer VS Code Extension
• CLI Reference — Danh sách đầy đủ các lệnh CLI: Intlayer CLI
• Intlayer with Nuxt — Hướng dẫn thiết lập đầy đủ cho Nuxt: intlayerwithnuxt.md
• Intlayer with Vue — Hướng dẫn thiết lập đầy đủ cho Vue: intlayerwithvite+vue.md