@tnet-store/i18n-stock

Shared i18n package cho hệ thống web & mobile apps của Trinity Net Technology.
Dùng để đồng bộ key/value translations (multi-language) và cung cấp API/React hook để thao tác thuận tiện.

🚀 QUAN TRỌNG: Hướng dẫn tạo key mới và quy trình merge

1. Setup ban đầu

Khi pull source code về, nhớ chạy yarn trước:

git pull origin main
yarn install

2. Tạo branch mới

Khi update/thêm ngôn ngữ, checkout nhánh mới hoặc nhánh đã có theo format:

# Tạo nhánh mới
git checkout -b feat/add-new-translations
# hoặc
git checkout -b fix/update-missing-keys

# Hoặc checkout nhánh đã có
git checkout feat/xxx

3. Tạo key mới trong locales

Bước 1: Thêm key vào locales/en.json (file gốc)

Mở file locales/en.json và thêm key mới theo cấu trúc nested:

{
  "button": {
    "newKey": "New Button Text"
  },
  "common": {
    "newMessage": "New message"
  }
}

Lưu ý:

• File en.json là file gốc, tất cả keys phải được định nghĩa ở đây trước
• Sử dụng cấu trúc nested (ví dụ: "section.subsection.key")
• Key phải là camelCase hoặc kebab-case

Bước 2: Thêm translation tương ứng vào các file locale khác

Sau khi thêm vào en.json, cần thêm translation vào các file:

• locales/zh-CN.json (Chinese Simplified)
• locales/zh-TW.json (Chinese Traditional - Taiwan)
• locales/zh-HK.json (Chinese Traditional - Hong Kong)

Ví dụ: Nếu thêm "button.newKey": "New Button Text" vào en.json, thì cần thêm:

• zh-CN.json: "button.newKey": "新按钮文本"
• zh-TW.json: "button.newKey": "新按鈕文本"
• zh-HK.json: "button.newKey": "新按鈕文本"

Bước 3: Kiểm tra translations

Chạy script để kiểm tra tất cả locales đã đầy đủ:

yarn check:i18n:all

Script này sẽ:

• Kiểm tra tất cả keys trong en.json đã có trong các locale khác chưa
• Kiểm tra placeholders (ví dụ: {{count}}) có khớp nhau không
• Báo lỗi nếu thiếu key hoặc placeholder không khớp

Bước 4: Generate keys và build

Sau khi thêm key, generate lại type-safe keys:

yarn gen:keys
# hoặc build toàn bộ
yarn build

4. Commit code

Sau khi thay đổi, commit với format chuẩn:

git commit -m "feat: add new translation keys for checkout flow"
# hoặc
git commit -m "fix: update missing translations in zh-CN"

Lưu ý quan trọng:

• Sử dụng prefix feat: cho tính năng mới (thêm key mới)
• Sử dụng prefix fix: cho sửa lỗi (sửa translation, thêm key thiếu)
• Mục đích: tránh version tăng không kiểm soát khi merge vào main
• CI sẽ tự động phân tích commit message và quyết định version bump (patch/minor/major)

5. Push và tạo Pull Request

git push origin feat/xxx

Sau đó tạo PR trên GitHub và merge vào main.

6. CI tự động build và publish

Sau khi merge vào main, GitHub Actions sẽ tự động:

• ✅ Chạy semantic-release
• ✅ Phân tích commit messages để quyết định version bump
• ✅ Build package
• ✅ Publish lên npm với version mới
• ✅ Tạo GitHub release và CHANGELOG

Không cần làm gì thêm, chỉ cần đợi CI chạy xong!

7. Cập nhật package trong app/web

Sau khi CI publish thành công (thường mất 2-3 phút), vào project app/web và cập nhật:

# Với npm
npm install @tnet-store/i18n-stock@latest

# Với yarn
yarn add @tnet-store/i18n-stock@latest

✨ Tính năng

• 📦 Centralized translations: dùng chung locales/*.json cho cả web (React) và app (React Native).
• 🔑 Type-safe keys: auto-generate type từ en.json → autocomplete khi gọi t().
• ⚡ React hooks: có sẵn useT() để dễ dùng trong component.
• 🔄 Hot language switch: hỗ trợ i18next.changeLanguage() runtime.
• 🚀 CI/CD ready: publish tự động qua GitHub Actions khi merge vào main.

📥 Cài đặt

Package được publish public trên npm:

yarn add @tnet-store/i18n-stock@latest
# hoặc npm
npm install @tnet-store/i18n-stock@latest

🛠 Cách dùng

1. Khởi tạo i18n

Trong entry file của app (ví dụ main.tsx với React, App.tsx với React Native):

import { initI18n } from "@tnet-store/i18n-stock";

// Khởi tạo với ngôn ngữ mặc định
initI18n({ lng: "en" });

2. Dùng hàm t()

import { t } from "@tnet-store/i18n-stock";

function Example() {
  return <h1>{t("button.viewQuotes")}</h1>;
}

3. Dùng hook useT()

import { useT } from "@tnet-store/i18n-stock";

export function Example() {
  const { t, i18n, lng } = useT();

  return (
    <>
      <p>Current language: {lng}</p>
      <p>{t("common.loading")}</p>
      <button onClick={() => i18n.changeLanguage(lng === "en" ? "zh-CN" : "en")}>
        Switch Language
      </button>
    </>
  );
}

🌍 Cấu trúc locales/

locales/
 ├─ en.json   # English (file gốc - tất cả keys phải có ở đây)
 ├─ zh-CN.json # Chinese (Simplified)
 ├─ zh-TW.json # Chinese (Traditional - Taiwan)
 └─ zh-HK.json # Chinese (Traditional - Hong Kong)

Ví dụ en.json:

{
  "button": {
    "login": "Login",
    "logout": "Logout",
    "viewQuotes": "View Quotes"
  },
  "common": {
    "loading": "Loading..."
  }
}

🔑 Type-safe Keys

Sau mỗi lần build, file src/__generated__/keys.ts sẽ được sinh tự động từ en.json.

import { t } from "@tnet-store/i18n-stock";
import type { TranslationKey } from "@tnet-store/i18n-stock";

function safeT<K extends TranslationKey>(key: K) {
  return t(key);
}

safeT("button.login");     // ✅
safeT("button.notExists"); // ❌ lỗi compile

📦 Scripts có sẵn

• yarn build – build TypeScript → dist/ và generate keys
• yarn check:i18n – check translations giữa các file locale
• yarn check:placeholders – check placeholders giữa các file locale
• yarn check:i18n:all – chạy full check cho tất cả locales (nên chạy trước khi commit)
• yarn gen:keys – generate type keys từ en.json
• yarn prepublishOnly – chạy full build + check + gen trước khi publish

🚀 Release Process

Release được tự động hóa hoàn toàn qua semantic-release:

• Không cần bump version thủ công trong package.json
• Không cần tạo git tag thủ công
• CI sẽ tự động:
  • Phân tích commit messages (feat/fix/breaking change)
  • Quyết định version bump (patch/minor/major)
  • Build và publish lên npm
  • Tạo GitHub release
  • Update CHANGELOG.md

Commit message format

• feat: xxx → minor version bump (1.0.0 → 1.1.0)
• fix: xxx → patch version bump (1.0.0 → 1.0.1)
• feat!: xxx hoặc BREAKING CHANGE: xxx → major version bump (1.0.0 → 2.0.0)

📜 License

MIT © Trinity Net Technology