Trình Biên Dịch Intlayer | Trích Xuất Nội Dung Tự Động cho i18n

Trình Biên Dịch Intlayer là gì?

Trình Biên Dịch Intlayer là một công cụ mạnh mẽ được thiết kế để tự động hóa quy trình quốc tế hóa (i18n) trong các ứng dụng của bạn. Nó quét mã nguồn của bạn (JSX, TSX, Vue, Svelte) để tìm các khai báo nội dung, trích xuất chúng và tự động tạo ra các tệp từ điển cần thiết. Điều này cho phép bạn giữ nội dung cùng vị trí với các component của mình trong khi Intlayer xử lý việc quản lý và đồng bộ hóa các từ điển đó.

Tại sao nên sử dụng Trình Biên Dịch Intlayer?

• Automation: Loại bỏ việc sao chép nội dung thủ công vào các từ điển.

• Speed: Trích xuất nội dung được tối ưu hóa đảm bảo quy trình build của bạn vẫn nhanh chóng.

• Developer Experience: Giữ các khai báo nội dung ngay tại nơi chúng được sử dụng, cải thiện khả năng bảo trì.

• Tự động hóa: Loại bỏ việc sao chép thủ công nội dung vào từ điển.
• Tốc độ: Tối ưu hóa việc trích xuất nội dung đảm bảo quá trình build của bạn vẫn nhanh.
• Trải nghiệm nhà phát triển: Giữ các khai báo nội dung ngay tại nơi chúng được sử dụng, cải thiện khả năng bảo trì.
• Cập nhật trực tiếp: Hỗ trợ Hot Module Replacement (HMR) để phản hồi ngay lập tức trong quá trình phát triển.

Xem bài viết blog Compiler vs. Declarative i18n để có sự so sánh sâu hơn.

Tại sao không sử dụng Trình Biên Dịch Intlayer?

Mặc dù trình biên dịch mang lại trải nghiệm "hoạt động ngay" tuyệt vời, nó cũng giới thiệu một số đánh đổi mà bạn nên biết:

• Sự mơ hồ của heuristic: Trình biên dịch phải đoán xem đâu là nội dung hướng đến người dùng so với logic ứng dụng (ví dụ: className="active", mã trạng thái, ID sản phẩm). Trong các codebase phức tạp, điều này có thể dẫn đến dương tính giả hoặc các chuỗi bị bỏ sót cần chú thích thủ công và ngoại lệ.

• Chỉ trích xuất tĩnh: Trích xuất dựa trên trình biên dịch dựa vào phân tích tĩnh. Các chuỗi chỉ tồn tại ở thời gian chạy (mã lỗi API, trường CMS, v.v.) không thể được phát hiện hoặc dịch bởi trình biên dịch một mình, vì vậy bạn vẫn cần một chiến lược i18n thời gian chạy bổ sung.

• Trích xuất chỉ tĩnh: Trích xuất dựa trên trình biên dịch dựa vào phân tích tĩnh. Các chuỗi chỉ tồn tại trong thời gian chạy (mã lỗi API, các trường CMS, v.v.) không thể được phát hiện hoặc dịch bởi trình biên dịch một mình, vì vậy bạn vẫn cần một chiến lược i18n runtime bổ sung.

Để có so sánh kiến trúc sâu hơn, xem bài viết blog Compiler vs. Declarative i18n.

Như một giải pháp thay thế, để tự động hóa quy trình i18n của bạn trong khi vẫn giữ quyền kiểm soát hoàn toàn đối với nội dung của bạn, Intlayer cũng cung cấp lệnh tự động trích xuất intlayer extract (xem tài liệu CLI), hoặc lệnh Intlayer: extract content to Dictionary từ tiện ích mở rộng Intlayer VS Code (xem tài liệu tiện ích mở rộng VS Code).

Cách sử dụng

The quickest way to wire the compiler in is the interactive setup: run npx intlayer init --interactive and select Compiler. On Vite there is nothing to configure — the compiler is plugged in directly through the intlayerCompiler() plugin. On Next.js the command scaffolds the babel.config.js shown below. The non-interactive intlayer init leaves the compiler setup untouched.

npm install vite-intlayer

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

# Dành cho Vue
npm install @intlayer/vue-compiler

# Dành cho Svelte
npm install @intlayer/svelte-compiler

npm install @intlayer/babel

const {
  intlayerExtractBabelPlugin,
  intlayerOptimizeBabelPlugin,
  getExtractPluginOptions,
  getOptimizePluginOptions,
} = require("@intlayer/babel");

module.exports = {
  presets: ["next/babel"],
  plugins: [
    // Trích xuất nội dung từ các component vào từ điển
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
    // Tối ưu hóa việc import bằng cách thay thế useIntlayer bằng việc import trực tiếp từ điển
    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
  ],
};

Cấu hình tùy chỉnh

Để tùy chỉnh hành vi của trình biên dịch, bạn có thể cập nhật tệp intlayer.config.ts trong thư mục gốc của dự án.

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  compiler: {
    /**
     * Cho biết trình biên dịch có nên được bật hay không.
     * Đặt thành 'build-only' để bỏ qua trình biên dịch trong quá trình phát triển và tăng tốc thời gian khởi động.
     */
    enabled: true,

    /**
     * Xác định đường dẫn tệp đầu ra. Thay thế `outputDir`.
     *
     * - Các đường dẫn bắt đầu bằng `./` được giải quyết tương đối so với thư mục component.
     * - Các đường dẫn bắt đầu bằng `/` được giải quyết tương đối so với thư mục gốc của dự án (`baseDir`).
     *
     * - Việc bao gồm biến `{{locale}}` trong đường dẫn sẽ cho phép tạo các từ điển được tách biệt theo ngôn ngữ.
     *
     * Ví dụ:
     * ```ts
     * {
     *   // Tạo tệp .content.ts đa ngôn ngữ bên cạnh component
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // Cách viết tương đương bằng template string
     * }
     * ```
     *
     * ```ts
     * {
     *   // Tạo tệp JSON tập trung theo ngôn ngữ trong thư mục gốc của dự án
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Cách viết tương đương bằng template string
     * }
     * ```
     *
     * Danh sách biến:
     *   - `fileName`: Tên tệp.
     *   - `key`: Khóa nội dung.
     *   - `locale`: Ngôn ngữ nội dung.
     *   - `extension`: Phần mở rộng tệp.
     *   - `componentFileName`: Tên tệp component.
     *   - `componentExtension`: Phần mở rộng tệp component.
     *   - `format`: Định dạng từ điển.
     *   - `componentFormat`: Định dạng từ điển component.
     *   - `componentDirPath`: Đường dẫn thư mục component.
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Cho biết liệu các component có nên được lưu sau khi được chuyển đổi hay không.
     * Bằng cách đó, trình biên dịch có thể được chạy một lần duy nhất để chuyển đổi ứng dụng, và sau đó nó có thể được gỡ bỏ.
     */
    saveComponents: false,

    /**
     * Chỉ chèn nội dung vào tệp đã tạo. Hữu ích cho đầu ra JSON i18next hoặc ICU MessageFormat cho mỗi ngôn ngữ.
     *
     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`
     */
    noMetadata: false,

    /**
     * Tiền tố khóa từ điển
     */
    dictionaryKeyPrefix: "", // Thêm một tiền tố tùy chọn cho các khóa từ điển được trích xuất
  },
};

export default config;

Tham khảo cấu hình trình biên dịch

Các thuộc tính sau có thể được cấu hình trong khối compiler của tệp intlayer.config.ts của bạn:

• enabled:

  • Loại: boolean | 'build-only'
  • Mặc định: true
  • Mô tả: Cho biết trình biên dịch có nên được bật hay không.

• dictionaryKeyPrefix:

  • Loại: string
  • Mặc định: ''
  • Mô tả: Tiền tố cho các khóa từ điển được trích xuất.

• transformPattern:

  • Loại: string | string[]
  • Mặc định: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • Mô tả: (Đã lỗi thời: hãy sử dụng build.traversePattern thay thế) Các mẫu để duyệt mã để tối ưu hóa.

• excludePattern:

  • Loại: string | string[]
  • Mặc định: ['**/node_modules/**']
  • Mô tả: (Đã lỗi thời: hãy sử dụng build.traversePattern thay thế) Các mẫu để loại trừ khỏi quá trình tối ưu hóa.

• output:

  • Loại: FilePathPattern
  • Mặc định: ({ key }) => 'compiler/${key}.content.json'
  • Mô tả: Xác định đường dẫn tệp đầu ra. Thay thế outputDir. Xử lý các biến động như {{locale}}, {{key}}, {{fileName}}, {{extension}}, {{format}}, {{dirPath}}, {{componentFileName}}, {{componentExtension}} và {{componentFormat}}. Có thể được đặt dưới dạng chuỗi bằng định dạng 'my/{{var}}/path' hoặc dưới dạng hàm.
  • Ghi chú: Các đường dẫn ./**/* được giải quyết tương đối so với component. Các đường dẫn /**/* được giải quyết tương đối so với baseDir của Intlayer.
  • Ghi chú: Nếu ngôn ngữ được xác định trong đường dẫn, các từ điển sẽ được tạo cho mỗi ngôn ngữ.
  • Ví dụ: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • Loại: boolean
  • Mặc định: false
  • Mô tả: Cho biết liệu siêu dữ liệu có nên được lưu trong tệp hay không. Nếu true, trình biên dịch sẽ không lưu siêu dữ liệu của từ điển (khóa, trình bao bọc nội dung). Hữu ích cho đầu ra JSON i18next hoặc ICU MessageFormat cho mỗi ngôn ngữ.
  • Ghi chú: Hữu ích nếu được sử dụng với plugin loadJSON.
  • Ví dụ: Nếu true: json { "key": "value" } Nếu false: json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • Loại: boolean
  • Mặc định: false
  • Mô tả: Cho biết liệu các component có nên được lưu sau khi được chuyển đổi hay không.

Điền các bản dịch còn thiếu

Intlayer cung cấp một công cụ CLI để giúp bạn điền các bản dịch còn thiếu. Bạn có thể sử dụng lệnh intlayer để kiểm tra và điền các bản dịch còn thiếu từ mã của mình.

npx intlayer test         # Kiểm tra xem có thiếu bản dịch không

npx intlayer fill         # Điền các bản dịch còn thiếu

Trích xuất

Intlayer cung cấp một công cụ CLI để giúp bạn trích xuất nội dung từ mã của mình. Bạn có thể sử dụng lệnh intlayer extract để trích xuất nội dung từ mã của mình.

npx intlayer extract

Để biết thêm chi tiết, hãy tham khảo tài liệu CLI