Dịch trang web Angular 21 (Vite) của bạn bằng Intlayer | Quốc tế hóa (i18n)

Mục lục

Intlayer là gì?

Intlayer là một thư viện quốc tế hóa (i18n) mã nguồn mở, sáng tạo, được thiết kế để đơn giản hóa việc hỗ trợ đa ngôn ngữ trong các ứng dụng web hiện đại.

Với Intlayer, bạn có thể:

• Dễ dàng quản lý các bản dịch bằng cách sử dụng các từ điển khai báo ở cấp độ component.
• Tự động cục bộ hóa (localize) siêu dữ liệu (metadata), route và nội dung.
• Đảm bảo hỗ trợ TypeScript với các kiểu dữ liệu được tự động tạo, cải thiện tính năng tự động hoàn thành và phát hiện lỗi.
• Hưởng lợi từ các tính năng nâng cao, chẳng hạn như tự động phát hiện ngôn ngữ và chuyển đổi ngôn ngữ linh hoạt.

Hướng dẫn từng bước để thiết lập Intlayer trong một Ứng dụng Angular

Xem Mẫu Ứng Dụng trên GitHub.

Bước 1: Cài đặt các gói phụ thuộc

Cài đặt các gói cần thiết bằng cách sử dụng npm:

npm install intlayer angular-intlayernpm install @angular-builders/custom-esbuild --save-devnpx intlayer init

• intlayer

  Gói cốt lõi cung cấp các công cụ quốc tế hóa cho việc quản lý cấu hình, bản dịch, khai báo nội dung, chuyển mã (transpilation), và các lệnh CLI.

• angular-intlayer Gói giúp tích hợp Intlayer vào ứng dụng Angular. Nó cung cấp các context providers và hooks cho quốc tế hóa trong Angular.

• @angular-builders/custom-esbuild Bắt buộc để tùy chỉnh cấu hình esbuild của Angular CLI.

Bước 2: Cấu hình dự án của bạn

Tạo một tập tin cấu hình để thiết lập ngôn ngữ cho ứng dụng của bạn:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Các ngôn ngữ khác của bạn
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Thông qua tệp cấu hình này, bạn có thể thiết lập các URL được địa phương hóa, chuyển hướng middleware, tên cookie, vị trí và phần mở rộng cho các khai báo nội dung của bạn, vô hiệu hóa nhật ký Intlayer trong bảng điều khiển và hơn thế nữa. Để xem danh sách đầy đủ các thông số khả dụng, tham khảo tài liệu cấu hình.

Bước 3: Tích hợp Intlayer vào Cấu hình Angular của bạn

Để tích hợp Intlayer với Angular CLI, bạn cần sử dụng một builder tùy chỉnh. Hướng dẫn này giả định bạn đang sử dụng Vite/esbuild (mặc định cho các dự án Angular 21).

Trước tiên, sửa đổi tập tin angular.json của bạn để sử dụng builder esbuild tùy chỉnh. Cập nhật cấu hình build và serve:

{  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-esbuild:application", // replace "@angular/build:application"          "options": {            "define": {              "process.env": "{}",            },            "plugins": ["./esbuild.plugins.ts"],            "browser": "src/main.ts",            // ...          },        },        "serve": {          "builder": "@angular-builders/custom-esbuild:dev-server", // replace "@angular/build:dev-server"          "options": {            "prebundle": {              "exclude": [                "intlayer",                "angular-intlayer",                "@intlayer/config/built",                "@intlayer/core"              ]          },        },      },    },  },}

Hãy chắc chắn thay thế your-app-name bằng tên thực tế của dự án của bạn trong tệp angular.json.

Tiếp theo, hãy tạo một tệp esbuild.plugins.ts ở thư mục gốc của dự án:

import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

Hàm intlayerEsbuildPlugin sẽ cấu hình esbuild cho Intlayer. Nó nhúng plugin để xử lý các tập tin khai báo nội dung và thiết lập các cấu hình tối ưu hiệu suất.

Người dùng NX: Các trình xây dựng Angular của NX tải các tệp plugin thông qua độ phân giải ESM gốc của Node và không biên dịch các tệp plugin TypeScript trực tiếp. Thay vào đó, hãy sử dụng tệp .mjs và cập nhật tham chiếu plugins trong angular.json tương ứng:

esbuild.plugins.mjs

Sao chép nội dung

Sao chép mã

Sao chép đoạn mã vào khay nhớ tạm (clipboard)

import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

Sau đó, trong angular.json, hãy trỏ đến "./esbuild.plugins.mjs" thay vì "./esbuild.plugins.ts".

Bước 4: Khai báo nội dung của bạn

Tạo và quản lý các khai báo nội dung của bạn để lưu trữ bản dịch:

Các khai báo nội dung của bạn có thể được định nghĩa ở bất kỳ đâu trong ứng dụng miễn là chúng nằm trong thư mục contentDir (mặc định là ./src). Và chúng phải có phần mở rộng file phù hợp với quy định về khai báo nội dung (mặc định là .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Để biết thêm chi tiết, hãy tham khảo tài liệu khai báo nội dung.

Bước 5: Sử dụng Intlayer trong Mã của bạn

Để khai thác các tính năng quốc tế hóa của Intlayer trên toàn bộ ứng dụng Angular của bạn, bạn cần cung cấp (provide) Intlayer trong cấu hình ứng dụng.

import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { provideIntlayer } from "angular-intlayer";import { routes } from "./app.routes";export const appConfig: ApplicationConfig = {  providers: [    provideRouter(routes),    provideIntlayer(), // Thêm provider cho Intlayer tại đây  ],};

Sau đó, bạn có thể sử dụng hàm useIntlayer bên trong bất kỳ component nào.

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

Và trong template của bạn:

<div class="content">  <h1>{{ content().title }}</h1>  <p>{{ content().congratulations }}</p></div>

Nội dung của Intlayer được trả về dưới dạng Signal, vì vậy bạn truy cập các giá trị bằng cách gọi tín hiệu (signal): content().title.

(Tùy chọn) Bước 6: Thay đổi ngôn ngữ cho nội dung của bạn

Để thay đổi ngôn ngữ của nội dung, bạn có thể sử dụng hàm setLocale được cung cấp bởi hàm useLocale. Nó cho phép bạn cài đặt ngôn ngữ cho ứng dụng và nội dung sẽ tự động cập nhật theo.

Tạo một component để chuyển đổi giữa các ngôn ngữ:

import { Component } from "@angular/core";import { CommonModule } from "@angular/common";import { useLocale } from "angular-intlayer";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule],  template: `    <div class="locale-switcher">      <select        [value]="locale()"        (change)="setLocale($any($event.target).value)"      >        @for (loc of availableLocales; track loc) {          <option [value]="loc">{{ loc }}</option>        }      </select>    </div>  `,})export class LocaleSwitcherComponent {  localeCtx = useLocale();  locale = this.localeCtx.locale;  availableLocales = this.localeCtx.availableLocales;  setLocale = this.localeCtx.setLocale;}

Sau đó, sử dụng component này trong tệp app.component.ts của bạn:

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";import { LocaleSwitcherComponent } from "./locale-switcher.component";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet, LocaleSwitcherComponent],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

Cấu hình TypeScript

Intlayer tận dụng Module Augmentation để nhận được những lợi ích từ TypeScript và làm cho cơ sở mã của bạn mạnh mẽ hơn.

Hãy chắc chắn rằng cấu hình TypeScript của bạn bao gồm các loại (types) được tạo tự động.

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

Cấu hình Git

Chúng tôi khuyên bạn nên bỏ qua các tệp do Intlayer tạo ra. Điều này giúp bạn tránh commit chúng vào kho lưu trữ Git.

Để thực hiện, bạn có thể thêm hướng dẫn sau vào tệp .gitignore:

# Bỏ qua các tệp do Intlayer tạo ra.intlayer

Tiện ích mở rộng VS Code

Để cải thiện trải nghiệm phát triển của bạn với Intlayer, bạn có thể cài đặt Tiện ích mở rộng VS Code chính thức của Intlayer.

Cài đặt từ VS Code Marketplace

Tiện ích này cung cấp:

• Tự động hoàn thành (Autocompletion) cho các khóa dịch (translation keys).
• Phát hiện lỗi theo thời gian thực đối với các bản dịch bị thiếu.
• Xem trước nội dung ngay trong dòng cho các nội dung đã dịch.
• Thao tác nhanh dễ dàng tạo và cập nhật các bản dịch.

Để biết thêm chi tiết về cách sử dụng tiện ích, hãy tham khảo tài liệu tiện ích mở rộng VS Code Intlayer.

Đi xa hơn

Để đi xa hơn nữa, bạn có thể triển khai visual editor hoặc externalize (đưa ra ngoài) nội dung của bạn bằng CMS.