Giới thiệu i18nGuard: Giải pháp kiểm tra i18n cho JS/TS

Tại sao cần i18nGuard?

Vấn đề quốc tế hóa (i18n) là một trong những thách thức lớn mà các nhà phát triển phải đối mặt khi xây dựng ứng dụng đa ngôn ngữ. Một chuỗi cứng nhắc bị bỏ sót trong mã nguồn, một khóa không có trong một ngôn ngữ, hay một khóa không được sử dụng trong nhiều tháng có thể dẫn đến một giao diện người dùng không đồng nhất và chưa hoàn chỉnh. Do đó, việc sử dụng các công cụ tự động hóa để phát hiện và xử lý những vấn đề này là rất cần thiết.

i18nGuard là gì?

i18nGuard là một công cụ kiểm tra và xác thực quốc tế hóa cho các dự án JavaScript/TypeScript, hỗ trợ i18next, React-Intl (FormatJS) và Lingui. Nó cung cấp một CLI, một tiện ích mở rộng cho VS Code, báo cáo SARIF cho việc quét mã, giả lập địa phương hóa và ngân sách độ phủ dịch thuật.

GitHub: deuwi/i18nGuard
npm (CLI): @i18nguard/cli

Tóm tắt nhanh

Phát hiện chuỗi cứng nhắc, khóa bị thiếu, và khóa không sử dụng.
Hỗ trợ i18next, React‑Intl (FormatJS), và Lingui.
CLI cho môi trường phát triển và CI, tiện ích mở rộng VS Code cho việc sửa lỗi một lần nhấp.
Báo cáo JSON/HTML/SARIF và ngưỡng độ phủ.

Các tính năng chính

1. Phát hiện thông minh

Phát hiện chuỗi cứng nhắc trong giao diện người dùng.
Xác thực các khóa bị thiếu và không sử dụng trên nhiều ngôn ngữ.

2. Hỗ trợ đa khung

Tích hợp với i18next, React‑Intl và Lingui.
Phản hồi nhanh trong VS Code với các sửa lỗi nhanh.

3. Thân thiện với CI/CD

JSON/HTML/SARIF báo cáo, fail-on-error để kiểm tra PR.
Ngân sách giả lập và độ phủ dịch thuật.

Hướng dẫn nhanh

Cài đặt i18nGuard

Để bắt đầu, bạn cần cài đặt CLI:

bash Copy

# Cài đặt toàn cục
npm install -g @i18nguard/cli

# Cài đặt cho dự án
npm install --save-dev @i18nguard/cli

Tạo cấu hình

Tạo một tệp i18nscan.config.ts tại thư mục gốc của dự án:

typescript Copy

import { defineConfig } from '@i18nguard/core';

export default defineConfig({
  library: 'i18next', // hoặc 'formatjs' hoặc 'lingui' hoặc 'auto'
  src: ['src/**/*.{ts,tsx,js,jsx}'],
  locales: ['en', 'fr', 'es'],
  defaultLocale: 'en',
  catalogs: {
    i18next: {
      pathPattern: 'public/locales/{locale}/{ns}.json',
      namespaces: ['common', 'auth', 'dashboard']
    }
  },
  budgets: {
    coverage: {
      fr: 95,
      es: 80
    },
    maxNewHardCodedPerPR: 0
  },
  ignore: ['**/*.test.*', '**/node_modules/**'],
  keygen: {
    strategy: 'filePathSlug',
    maxLen: 60
  },
  report: {
    formats: ['json', 'html'],
    outputDir: 'reports/i18n'
  }
});

Chạy quét

Chạy lệnh sau để quét:

bash Copy

# Quét cơ bản
i18nguard scan

# Báo cáo JSON và HTML
i18nguard scan --format json --output results.json
i18nguard report --input results.json --format html --output report.html

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

i18nGuard có một tiện ích mở rộng cho VS Code giúp bạn kiểm tra và sửa lỗi ngay trong mã nguồn:

Phát hiện thời gian thực cho chuỗi cứng nhắc, khóa bị thiếu và không sử dụng.
Sửa lỗi nhanh để ngoại hóa chuỗi và ghi khóa vào danh mục dịch thuật.

CI/CD và SARIF

Tích hợp i18nGuard vào quy trình CI/CD của bạn với GitHub Actions:

yaml Copy

name: i18n Validation
on: [push, pull_request]

jobs:
  i18n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx i18nguard scan --format sarif --output i18n.sarif --fail-on-error
      - name: Upload SARIF (GitHub code scanning)
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: i18n.sarif

Ngân sách chất lượng

Thiết lập ngân sách giúp bạn đảm bảo chất lượng dịch thuật:

maxNewHardCodedPerPR: 0 để ngăn chặn chuỗi cứng nhắc mới.
Ngưỡng độ phủ theo ngôn ngữ để giữ cho danh mục dịch thuật luôn khỏe mạnh.

Kết luận

i18nGuard là một công cụ mạnh mẽ giúp các nhà phát triển dễ dàng kiểm tra và duy trì chất lượng quốc tế hóa trong ứng dụng của họ. Hãy bắt đầu sử dụng ngay hôm nay để đảm bảo rằng giao diện người dùng của bạn luôn hoàn hảo và đồng nhất trên mọi ngôn ngữ.

Câu hỏi thường gặp

i18nGuard có hỗ trợ các khung khác không?

Có, i18nGuard hỗ trợ i18next, React‑Intl và Lingui.

Làm thế nào để tôi có thể cài đặt tiện ích mở rộng VS Code?

Bạn có thể cài đặt tiện ích mở rộng từ Marketplace hoặc tải xuống tệp VSIX từ repo của chúng tôi.

Tài nguyên tham khảo

Nếu bạn thấy bài viết hữu ích, hãy để lại một ⭐ trên GitHub và chia sẻ phản hồi của bạn!

Giảm thiểu chuỗi cứng nhắc: Giới thiệu i18nGuard cho JS/TS