@intlayer/docs 9.4.2 → 9.4.3

package/blog/vi/i18n_in_ci_cd_pipelines.md

@@ -0,0 +1,247 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Tự động hóa dịch thuật trong CI/CD mà không xuất bản nội dung kém chất lượng"
+description: Ba giai đoạn tự động hóa i18n, pre-push, pull request và runtime. Cách chặn build dựa trên độ bao phủ, tự động điền an toàn và tránh vòng lặp commit vô tận trong CI.
+keywords:
+  - tự động hóa dịch thuật ci
+  - i18n ci cd
+  - github actions dịch thuật
+  - husky pre-push
+  - bản địa hóa liên tục
+  - pipeline dịch thuật
+slugs:
+  - blog
+  - i18n-in-ci-cd-pipelines
+author: aymericzip
+---
+
+# Tự động hóa dịch thuật trong CI/CD mà không xuất bản nội dung kém chất lượng
+
+Dịch thuật thủ công không thể theo kịp tốc độ phát hành phần mềm hiện đại. Một lập trình viên thêm một chuỗi văn bản vào thứ Sáu, việc trích xuất dời sang sprint tiếp theo, và tới lúc đó ba ngôn ngữ khác đã bị tụt hậu. Tự động hóa bản thân nó rất đơn giản. Tự động hóa mà không âm thầm đưa các bản dịch máy móc chưa qua kiểm duyệt tới khách hàng mới là điều đáng để đầu tư suy nghĩ.
+
+## Mục lục
+
+<TOC/>
+
+## Bạn không cần di chuyển mã nguồn để tự động hóa
+
+Các cấu trúc pipeline dưới đây hoàn toàn độc lập với thư viện, và công cụ cũng vậy. Nếu các thông điệp của bạn là các danh mục JSON cho i18next, next-intl, react-intl, vue-i18n hoặc next-translate, [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/plugins/sync-json.md) sẽ đọc và ghi trực tiếp vào các file đó tại chỗ:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // hoặc "icu" cho next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Ứng dụng của bạn vẫn tiếp tục import những gì nó vốn import. Các tác vụ CI sau đó sẽ tự động điền và kiểm tra các danh mục hiện có, và diff mà reviewer nhìn thấy chỉ là thay đổi trên `locales/fr/checkout.json`, không phải là một đợt di chuyển kiến trúc mã nguồn. Ngoài ra còn có [plugin Sync PO](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/plugins/sync-po.md) cho quy trình gettext và [adapter tương thích](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/compat/index.md) nếu bạn muốn giữ nguyên runtime API.
+
+## Phân tách rào chắn kiểm tra (gate) khỏi quá trình điền dữ liệu (fill)
+
+Hai nhiệm vụ hoàn toàn khác biệt này thường xuyên bị nhầm lẫn.
+
+Một **gate** là một kiểm tra có thể thất bại. Nó tuyên bố bản build này không được phép phát hành vì thiếu các locale bắt buộc. Nó không ghi bất kỳ file nào.
+
+Một **fill** là một thao tác thay đổi dữ liệu. Nó sinh ra các bản dịch còn thiếu và commit chúng. Nó không bao giờ làm fail một bản build.
+
+Chỉ chạy fill đồng nghĩa với việc không bao giờ có gì bị chặn, và văn bản máy dịch chưa qua kiểm duyệt sẽ được đẩy thẳng lên production. Chỉ chạy gate đồng nghĩa với việc build liên tục báo đỏ và con người phải can thiệp thủ công mỗi lần. Hầu hết các đội ngũ đều cần cả hai, gắn với các trigger khác nhau: fill trên pull request, gate khi merge vào release branch.
+
+## Nơi tự động hóa có thể hoạt động
+
+| Giai đoạn      | Trigger   | Phù hợp cho                               | Chi phí                                            |
+| :------------- | :-------- | :---------------------------------------- | :------------------------------------------------- |
+| Hook pre-push  | Git local | Phản hồi nhanh, không tốn phút CI         | Chạy trên máy lập trình viên và dùng API key riêng |
+| Pull request   | Job CI    | Review trước khi merge, tập trung secrets | Tốn phút CI cộng với chi phí gọi model theo mỗi PR |
+| Release branch | Job CI    | Rào chắn nghiêm ngặt về độ bao phủ        | Rẻ, không gọi AI model                             |
+| Runtime        | CMS       | Sửa nội dung mà không cần build lại       | Phụ thuộc vào dịch vụ lưu trữ                      |
+
+## Pre-push: vòng lặp nhanh nhất
+
+Husky chạy việc điền bản dịch trước khi mã nguồn rời khỏi máy cá nhân, do đó các bản dịch sẽ tới trong cùng một push với các chuỗi mới được tạo ra.
+
+```bash fileName=".husky/pre-push"
+npx intlayer build
+npx intlayer fill --unpushed --mode complete
+```
+
+`--unpushed` giới hạn phạm vi xử lý cho các nội dung chưa được push, giúp tránh việc push bị chậm cả phút mỗi lần. `--mode complete` chỉ điền những gì còn thiếu mà không ghi đè lên các mục đã có giá trị, đảm bảo bản dịch đã duyệt không bao giờ bị thay thế âm thầm.
+
+Trong mô hình monorepo, phân chia phạm vi cho từng ứng dụng:
+
+```bash fileName=".husky/pre-push"
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
+```
+
+Nhược điểm rất rõ ràng: mỗi lập trình viên đều cần một API key và chi phí đè nặng lên người thực hiện push. Đó là lý do hầu hết các nhóm chuyển bước này sang CI khi quy mô bắt đầu tăng.
+
+## Pull request: điền dữ liệu ngay tại nơi diễn ra review
+
+Cùng một quy trình đó trong GitHub Actions, giới hạn trong phạm vi diff:
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "autofill-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npx intlayer build
+      - run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+      - name: Commit
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git config --local user.email "action@github.com"
+            git config --local user.name "GitHub Action"
+            git add .
+            git commit -m "chore: auto-fill missing translations [skip ci]"
+            git push origin HEAD:${{ github.head_ref }}
+          fi
+```
+
+Bốn chi tiết ở đây mang tính quyết định:
+
+- **`fetch-depth: 0`** là bắt buộc để `--git-diff` hoạt động. Bản shallow clone không có base để so sánh diff và việc fill sẽ âm thầm không xử lý gì cả.
+- **`[skip ci]` trong commit message** ngăn workflow tự kích hoạt chính nó lặp vô tận. Thiếu nó, commit sẽ kích hoạt lượt chạy mới, lượt chạy đó lại commit tiếp, đốt sạch ngân sách CI qua đêm.
+- **`concurrency` kết hợp `cancel-in-progress`** ngăn hai lần push cạnh tranh ghi đè lên cùng các file.
+- **`--git-diff`** giới hạn quá trình fill chỉ trong những gì thay đổi ở PR. Bỏ quên cờ này, bạn sẽ dịch lại toàn bộ danh mục ở mọi lượt chạy.
+
+Các bản dịch xuất hiện dưới dạng commit trên nhánh PR, giúp reviewer có thể xem xét chúng trực tiếp trong diff. Đó là toàn bộ lý do nên làm điều này tại PR thay vì đợi sau khi merge.
+
+## Release branch: rào chắn kiểm tra (gate)
+
+Gate không cần gọi model và phải chạy rất nhanh.
+
+```yaml fileName=".github/workflows/ci.yml"
+- run: npm run test:i18n
+```
+
+Được hỗ trợ bởi một bài test xác nhận độ bao phủ thay vì chỉ trông cậy vào báo cáo văn bản của CLI:
+
+```ts fileName="i18n.test.ts"
+import { listMissingTranslations } from "intlayer/cli";
+
+test("has no missing required locales", async () => {
+  const result = await listMissingTranslations();
+  if (result.missingRequiredLocales.length > 0) {
+    console.log(result.missingTranslations);
+  }
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+Lệnh `npx intlayer content test` in báo cáo nhưng thoát với mã 0, chỉ có tác dụng thông báo chứ không chặn quy trình. Hãy dùng nó ở máy local; còn trên CI, hãy dùng kiểm thử với assertion. Chi tiết hơn trong [phát hiện bản dịch còn thiếu](https://github.com/aymericzip/intlayer/blob/main/docs/blog/vi/detecting_missing_translations.md).
+
+## `requiredLocales` là yếu tố giúp gate tồn tại trong thực tế
+
+Một rào chắn yêu cầu đủ cả mười tám ngôn ngữ sẽ chặn mọi đợt phát hành cho đến khi ngôn ngữ chậm nhất hoàn tất, và kết quả là nó sẽ bị vô hiệu hóa trong vòng một tháng.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Khai báo tất cả các ngôn ngữ bạn hỗ trợ, nhưng chỉ bắt buộc các ngôn ngữ thực sự cần thiết để chặn đợt phát hành. Phần còn lại được bổ sung bất đồng bộ và không làm gián đoạn kế hoạch deploy.
+
+## Đưa toàn bộ bản dịch ra khỏi kho mã nguồn (repo)
+
+Một mô hình khác là chỉ khai báo một locale gốc trong code và quản lý phần còn lại từ xa thông qua CMS có Live Sync. Việc sửa đổi nội dung lúc này không yêu cầu build lại ứng dụng, tách rời hoàn toàn chu kỳ biên tập nội dung khỏi chu kỳ triển khai kỹ thuật.
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    liveSync: true,
+  },
+};
+
+export default config;
+```
+
+Cách này phù hợp với các nhóm nơi người phụ trách nội dung không phải là lập trình viên. Đó là một sự đánh đổi: bạn có được sự tự chủ trong chỉnh sửa nhưng mất đi tính chất git checkout phản ánh chính xác 100% những gì hiển thị trên màn hình. Chi tiết tại [tài liệu CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_CMS.md).
+
+Lưu ý rằng `clientSecret` là thông tin xác thực phía server. Nó chỉ được nằm trong CI secrets và biến môi trường server, tuyệt đối không được đưa vào bundle phía client.
+
+## Giới hạn thực tế cần nhìn nhận thẳng thắn
+
+Tất cả những điều trên chỉ tự động hóa **độ bao phủ**, không tự động hóa **chất lượng**. Một lượt điền tự động biến một khoảng trống nhìn thấy được thành một khoảng trống vô hình: audit báo xanh vì key đã có giá trị, nhưng chưa có con người nào đọc qua câu chữ đó.
+
+Điều này có thể chấp nhận được với công cụ nội bộ, changelog hoặc ngôn ngữ beta. Nhưng không thể chấp nhận được với trang bảng giá, điều khoản pháp lý, thông báo lỗi thanh toán hoặc bất cứ điều gì khách hàng đọc trước khi đưa ra quyết định. Hãy chuyển các phần quan trọng đó qua quy trình duyệt của con người và luôn dùng `--mode complete` để văn bản đã duyệt không bao giờ bị ghi đè.
+
+Cung cấp ngữ cảnh cho model để đầu ra ít nhất có sự nhất quán:
+
+```ts
+ai: {
+  applicationContext: "Ứng dụng xuất hóa đơn B2B. Giọng văn trang trọng. Tuyệt đối không dịch tên sản phẩm.",
+}
+```
+
+## Các sai lầm thường gặp
+
+- **Quên `[skip ci]` trong commit tự động.** Workflow tự kích hoạt lại trong vòng lặp vô tận.
+- **Shallow clone khi dùng `--git-diff`.** Không có base để so sánh, không có gì được điền và không có cảnh báo nào.
+- **Điền toàn bộ catalog ở mỗi lần chạy.** Hãy giới hạn với `--git-diff` hoặc `--unpushed` để kiểm soát chi phí.
+- **Dùng báo cáo CLI làm rào chắn (gate).** Lệnh thoát với mã 0 nên không chặn được lỗi.
+- **Bắt buộc mọi ngôn ngữ.** Rào chắn sẽ bị gỡ bỏ ngay lần đầu tiên nó làm nghẽn đợt phát hành.
+- **Có job fill nhưng không có gate ở đâu cả.** Không có gì báo lỗi và văn bản dịch thô từ máy móc lên thẳng production.
+- **Để lộ API key của model trong repo.** Phải đưa vào CI secrets tương tự như `clientSecret`.
+
+## Tìm hiểu thêm
+
+- [CI/CD: tự động sinh bản dịch với Husky, GitHub Actions và CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/CI_CD.md)
+- [Kiểm thử nội dung và chặn bản build dựa trên độ bao phủ](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/testing.md)
+- [autoFill: sinh file khai báo cho từng locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/autoFill.md)
+- [Tài liệu tham khảo cấu hình: `locales`, `requiredLocales`, `editor`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md)
+- [Báo cáo benchmark so sánh giữa các framework](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/benchmark/index.md)
+- [Adapter tương thích i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/compat/i18next.md)
+- [Cách phát hiện các bản dịch còn thiếu](https://github.com/aymericzip/intlayer/blob/main/docs/blog/vi/detecting_missing_translations.md)
+- [Cách kiểm thử bản dịch mà không tạo ra các bài test dễ vỡ](https://github.com/aymericzip/intlayer/blob/main/docs/blog/vi/i18n_testing_strategies.md)

package/blog/vi/i18n_meaning.md

@@ -19,8 +19,6 @@ author: aymericzip
 
 # Ý nghĩa i18n: Quốc tế hóa là gì và tại sao nó lại quan trọng?
 
-![minh họa i18n](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## Hiểu về "Ý nghĩa i18n"
 
 Nếu bạn tham gia vào lĩnh vực phát triển phần mềm, thiết kế web hoặc tiếp thị kỹ thuật số, có thể bạn đã bắt gặp thuật ngữ **i18n**. **Ý nghĩa i18n** thực sự chỉ đơn giản là một từ viết tắt bằng số cho **internationalization** (quốc tế hóa).

package/blog/vi/i18n_testing_strategies.md

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Cách kiểm thử bản dịch mà không tạo ra các bài test dễ vỡ"
+description: Những gì đáng để kiểm thử trong một ứng dụng i18n và những gì không nên. Kiểm thử render dựa trên Provider, giả bản địa hóa (pseudolocalization), độ bao phủ RTL và số nhiều, cùng bẫy snapshot.
+keywords:
+  - kiểm thử bản dịch
+  - i18n testing
+  - testing library i18n
+  - giả bản địa hóa
+  - test provider locale
+  - snapshot test i18n
+slugs:
+  - blog
+  - i18n-testing-strategies
+author: aymericzip
+---
+
+# Cách kiểm thử bản dịch mà không tạo ra các bài test dễ vỡ
+
+Hầu hết các bộ kiểm thử i18n đều thất bại theo một trong hai cách. Hoặc là chúng xác nhận văn bản theo nghĩa đen, khiến mọi thay đổi nhỏ về từ ngữ làm hỏng năm mươi bài test và đội ngũ phát triển quyết định xóa bỏ chúng. Hoặc là chúng chỉ render mọi thứ ở locale mặc định, không chứng minh được điều gì về mười bảy ngôn ngữ còn lại. Cả hai đều dẫn đến cùng một kết quả: một bộ test không ai tin tưởng.
+
+## Mục lục
+
+<TOC/>
+
+## Các mẫu kiểm thử không phụ thuộc vào thư viện
+
+Mọi mẫu bên dưới đều hoạt động trên bất kỳ stack i18n nào. Thay thế provider bằng `I18nextProvider`, `NextIntlClientProvider` hoặc `IntlProvider` thì các bài kiểm thử vẫn giống hệt nhau, bởi vì chúng xác nhận kết quả được render thay vì kiểm tra API riêng của thư viện.
+
+Công cụ kiểm tra độ bao phủ cũng có thể chuyển đổi dễ dàng: với [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/plugins/sync-json.md) trỏ vào các danh mục hiện có, hoặc một [adapter tương thích](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/compat/index.md) đặt bí danh cho các import hiện tại, xác nhận độ bao phủ sẽ chạy trực tiếp trên file JSON bạn đang có.
+
+## Xác định những gì bạn thực sự đang kiểm thử
+
+Chất lượng dịch thuật không thể kiểm tra bằng mã test. Không có assertion nào có thể cho bạn biết tiếng Đức có tự nhiên hay không, và cố gắng làm điều đó chỉ khiến bộ test ngập tràn các chuỗi hardcode.
+
+Những gì máy móc có thể và đáng để kiểm thử:
+
+| Đáng kiểm thử                              | Không đáng kiểm thử              |
+| :----------------------------------------- | :------------------------------- |
+| Mỗi locale bắt buộc đều có giá trị         | Câu từ có mượt mà hay không      |
+| Đúng locale được truyền vào component      | Văn bản chính xác của từng nhãn  |
+| Dạng số nhiều hoạt động cho từng phân loại | Người dịch có làm tốt việc không |
+| Locale RTL thiết lập đúng hướng và mirror  | Mọi chuỗi trong tất cả ngôn ngữ  |
+| Ngày và số được định dạng theo đúng locale | Tính chính xác nội bộ của `Intl` |
+
+Độ bao phủ nên được kiểm tra trong một bài test hướng dữ liệu duy nhất, không phải trong bài test component. Điều này được thảo luận trong [cách phát hiện bản dịch còn thiếu](https://github.com/aymericzip/intlayer/blob/main/docs/blog/vi/detecting_missing_translations.md); bài viết này tập trung vào phần còn lại.
+
+## Render dưới Provider và truy vấn theo Role
+
+Mẫu cốt lõi là gắn component bên trong một locale provider và truy vấn theo role hoặc test id thay vì theo chuỗi văn bản.
+
+```tsx fileName="CartSummary.test.tsx"
+import { render, screen } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+import { CartSummary } from "./CartSummary";
+
+test("render tiêu đề tóm tắt bằng tiếng Pháp", () => {
+  render(
+    <IntlayerProvider locale="fr-FR">
+      <CartSummary />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByRole("heading")).toBeInTheDocument();
+});
+```
+
+Truy vấn bằng `getByRole("heading")` vẫn an toàn khi văn bản thay đổi. `getByText("Récapitulatif")` sẽ hỏng ngay khi sửa chữ. Chỉ sử dụng chuỗi văn bản cố định khi chính chuỗi đó là đối tượng cần kiểm tra, điều vốn hiếm khi xảy ra.
+
+Đối với các thuộc tính như `aria-label`, bạn cần chuỗi thô thay vì một node có thể render. Trong React, các mục `useIntlayer` cung cấp trường `.value` cho mục đích này.
+
+## Tham số hóa các bài kiểm thử qua nhiều locale
+
+Một khối kiểm thử duy nhất chạy trên tất cả các locale có giá trị hơn nhiều so với việc viết từng bài test riêng cho mỗi ngôn ngữ.
+
+```tsx fileName="direction.test.tsx"
+import { getHTMLTextDir } from "intlayer";
+import { render } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+
+describe.each(["en", "fr", "ja", "ar"])("locale %s", (locale) => {
+  it("render mà không bị fallback về key", () => {
+    const { container } = render(
+      <IntlayerProvider locale={locale}>
+        <CartSummary />
+      </IntlayerProvider>
+    );
+
+    // Việc key bị render có nghĩa là quá trình tìm kiếm thất bại.
+    expect(container.textContent).not.toMatch(/^[a-z]+(\.[a-z]+)+$/);
+  });
+
+  it("thiết lập đúng hướng văn bản", () => {
+    expect(getHTMLTextDir(locale)).toBe(locale === "ar" ? "rtl" : "ltr");
+  });
+});
+```
+
+Assertion đầu tiên mang lại lợi ích phổ quát: nếu việc tìm kiếm thất bại và thư viện in ra key, DOM sẽ xuất hiện cấu trúc dạng `cart.summary.title`. Điều này bắt được cả một nhóm lỗi mà không cần chỉ định bất kỳ chuỗi cụ thể nào.
+
+## Giả bản địa hóa (Pseudolocalization) phát hiện những gì danh mục bỏ sót
+
+Thêm một locale giả để biến đổi mọi chuỗi, ví dụ biến `Checkout` thành `[!!! Çĥéçķöũţ !!!]`. Sau đó render trang web bằng locale này.
+
+Bất cứ nội dung nào vẫn hiển thị bằng tiếng Anh thông thường đều là nội dung bị hardcode trong mã nguồn. Không một quy trình kiểm tra danh mục nào có thể thấy được điều này, bởi vì đối với công cụ, chuỗi đó chưa từng tồn tại. Các dấu ngoặc vuông đóng vai trò thứ hai: chúng kéo dài văn bản thêm khoảng 30 phần trăm, làm lộ ra các lỗi vỡ giao diện trước khi gặp phải chúng trong tiếng Đức.
+
+Nên chạy bước này như một đợt kiểm thử trực quan hoặc end-to-end thay vì unit test, vì lỗi hiển thị trực tiếp trước mắt.
+
+## Số nhiều cần bài kiểm tra theo từng danh mục, không phải theo ngôn ngữ
+
+Lỗi số nhiều thường bị ẩn đi vì tiếng Anh chỉ có hai dạng và hầu hết lập trình viên chỉ kiểm thử hai dạng đó. Tiếng Ba Lan có bốn dạng, tiếng Ả Rập có sáu dạng.
+
+```ts fileName="plural.test.ts"
+// Tiếng Ả Rập kiểm tra zero, one, two, few, many, other.
+describe.each([0, 1, 2, 3, 11, 100])("số lượng %i", (count) => {
+  it("tạo ra một chuỗi không rỗng trong tiếng Ả Rập", () => {
+    expect(formatItems(count, "ar")).not.toBe("");
+  });
+});
+```
+
+Hãy chọn các con số tương ứng với từng danh mục CLDR cho ngôn ngữ phức tạp nhất của bạn thay vì chỉ thử 1 và 2 ở mọi nơi. `Intl.PluralRules` cho biết một số rơi vào danh mục nào, giúp bạn xây dựng tập mẫu mà không phải đoán mò. Xem thêm về các danh mục trong [bài viết về định dạng thông điệp ICU](https://github.com/aymericzip/intlayer/blob/main/docs/blog/vi/icu_message_format.md).
+
+## Cái bẫy của Snapshot test
+
+Snapshot và i18n là một sự kết hợp tồi. Snapshot của một component đa ngôn ngữ sẽ mã hóa toàn bộ văn bản trong đó: khi một dịch giả sửa lỗi chính tả trong tiếng Bồ Đào Nha, một bài test xanh biến thành đỏ trong một file mà người review không thể hiểu rõ. Sau vài lần như vậy, ai đó sẽ chạy `-u` mà không đọc diff, và snapshot hoàn toàn mất đi giá trị.
+
+Nếu bạn muốn dùng snapshot, hãy chỉ chụp trên một locale duy nhất và coi đó là kiểm tra cấu trúc chứ không phải kiểm tra nội dung. Mọi chi tiết phụ thuộc locale nên nằm trong các assertion rõ ràng.
+
+## Kiểm thử quá trình xác định locale, không chỉ là việc render
+
+Lỗi i18n phổ biến nhất trên môi trường production không phải là chuỗi bị thiếu. Đó là việc chọn sai locale: URL ghi `/fr/`, client đọc `navigator.language`, và hai bên xung đột.
+
+Kiểm tra trực tiếp thứ tự giải quyết locale như một hàm thuần túy, tách biệt khỏi component:
+
+```ts fileName="locale-resolution.test.ts"
+it("ưu tiên URL hơn tùy chọn đã lưu", () => {
+  expect(resolveLocale({ url: "/fr/about", stored: "de", header: "ja" })).toBe(
+    "fr"
+  );
+});
+
+it("fallback về header khi URL không có tiền tố", () => {
+  expect(resolveLocale({ url: "/about", stored: null, header: "ja" })).toBe(
+    "ja"
+  );
+});
+```
+
+Đây là bài kiểm tra i18n có giá trị cao nhất mà hầu hết dự án đều thiếu, và nó hoàn toàn không cần tới DOM.
+
+## Chạy cái gì và ở đâu
+
+- **Unit**: Lựa chọn locale, bộ định dạng, các danh mục số nhiều. Nhanh, không cần DOM.
+- **Component**: Một lần render dựa trên provider cho mỗi locale, kiểm tra role và việc không có key thô.
+- **Độ bao phủ**: Một bài test hướng dữ liệu xác nhận không thiếu locale bắt buộc nào.
+- **Visual hoặc E2E**: Chạy thử pseudolocalization và một trang RTL, vì đây là các lỗi giao diện trực quan.
+
+Giữ ba phần đầu trong pipeline CI tại mỗi commit. Phần cuối cùng nên chạy định kỳ ban đêm để tiết kiệm tài nguyên.
+
+## Các sai lầm thường gặp
+
+- **Xác nhận văn bản theo nghĩa đen ở khắp nơi.** Khiến bộ test chắc chắn bị xóa bỏ sau vài tháng.
+- **Chụp snapshot các component đã địa phương hóa.** Người dịch làm đứt gãy build và reviewer phê duyệt mà không đọc.
+- **Chỉ kiểm thử locale mặc định.** Locale duy nhất không bao giờ bị thiếu.
+- **Chỉ kiểm thử 1 và 2 cho dạng số nhiều.** Bỏ sót toàn bộ danh mục mà tiếng Anh không có.
+- **Mock toàn bộ thư viện i18n.** Lúc đó bạn chỉ đang kiểm tra xem mock có trả về chuỗi hay không.
+- **Không bao giờ kiểm tra logic chọn locale.** Lỗi phổ biến nhất ngoài đời thực và dễ kiểm thử nhất.
+
+## Tìm hiểu thêm
+
+- [Kiểm thử nội dung: kiểm toán CLI, API lập trình và UI assertion](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/testing.md)
+- [Plugin ESLint: phát hiện chuỗi hardcode và nội dung không sử dụng](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/eslint.md)
+- [Bộ định dạng và tiện ích locale, bao gồm `getHTMLTextDir`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/formatters.md)
+- [Báo cáo benchmark so sánh giữa các framework](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/benchmark/index.md)
+- [Adapter tương thích react-i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/compat/react-i18next.md)
+- [Cách phát hiện bản dịch còn thiếu](https://github.com/aymericzip/intlayer/blob/main/docs/blog/vi/detecting_missing_translations.md)
+- [Định dạng thông điệp ICU: số nhiều, select và skeleton](https://github.com/aymericzip/intlayer/blob/main/docs/blog/vi/icu_message_format.md)

package/blog/vi/intlayer_with_i18next.md

@@ -74,15 +74,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > cờ `--interactive` là tùy chọn. Sử dụng `intlayer-cli init` nếu bạn là tác nhân AI.

package/blog/vi/intlayer_with_next-i18next.md

@@ -67,15 +67,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > cờ `--interactive` là tùy chọn. Sử dụng `intlayer-cli init` nếu bạn là tác nhân AI.

package/blog/vi/intlayer_with_next-intl.md

@@ -69,15 +69,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > cờ `--interactive` là tùy chọn. Sử dụng `intlayer-cli init` nếu bạn là tác nhân AI.

package/blog/vi/intlayer_with_react-i18next.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > cờ `--interactive` là tùy chọn. Sử dụng `intlayer-cli init` nếu bạn là tác nhân AI.

package/blog/vi/intlayer_with_react-intl.md

@@ -66,15 +66,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > cờ `--interactive` là tùy chọn. Sử dụng `intlayer-cli init` nếu bạn là tác nhân AI.

package/blog/vi/intlayer_with_vue-i18n.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > cờ `--interactive` là tùy chọn. Sử dụng `intlayer-cli init` nếu bạn là tác nhân AI.