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

Mục lục

Tại sao Intlayer thay thế các lựa chọn thay thế?

So với các giải pháp chính như ngx-translate hay angular-l10n, Intlayer là giải pháp đi kèm với các tính năng tối ưu hóa tích hợp như:

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.

1. 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:

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   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.

2. 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:

   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";
   
   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.

3. 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:

   angular.json

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   {  "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:

   esbuild.plugins.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   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 mã vào 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".

4. 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,md,mdx,yaml,yml}).

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

5. 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.

   src/app/app.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   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.

   src/app/app.component.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   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:

   src/app/app.component.html

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   <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.

6. 6

   Thay đổi ngôn ngữ cho nội dung của bạn

   Tùy chọ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ữ:

   src/app/locale-switcher.component.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   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:

   src/app/app.component.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   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.