@tnet-store/i18n-stock 1.357.0 → 1.359.0

package/README.md

@@ -1,17 +1,148 @@
-# @tnet-i18n/i18n
+# @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**:
+
+```bash
+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:
+
+```bash
+# 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:
+
+```json
+{
+  "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 đủ:
+
+```bash
+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:
+
+```bash
+yarn gen:keys
+# hoặc build toàn bộ
+yarn build
+```
+
+### 4. Commit code
+
+Sau khi thay đổi, commit với format chuẩn:
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+# 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 release.
+- 🚀 **CI/CD ready**: publish tự động qua GitHub Actions khi merge vào main.
 
 ---
 
@@ -20,9 +151,9 @@
 Package được publish public trên npm:
 
 ```bash
-yarn add @tnet-i18n/i18n
+yarn add @tnet-store/i18n-stock@latest
 # hoặc npm
-npm install @tnet-i18n/i18n
+npm install @tnet-store/i18n-stock@latest
 ```
 
 ---
@@ -34,7 +165,7 @@ npm install @tnet-i18n/i18n
 Trong **entry file** của app (ví dụ `main.tsx` với React, `App.tsx` với React Native):
 
 ```ts
-import { initI18n } from "@tnet-i18n/i18n";
+import { initI18n } from "@tnet-store/i18n-stock";
 
 // Khởi tạo với ngôn ngữ mặc định
 initI18n({ lng: "en" });
@@ -43,7 +174,7 @@ initI18n({ lng: "en" });
 ### 2. Dùng hàm `t()`
 
 ```tsx
-import { t } from "@tnet-i18n/i18n";
+import { t } from "@tnet-store/i18n-stock";
 
 function Example() {
   return <h1>{t("button.viewQuotes")}</h1>;
@@ -53,7 +184,7 @@ function Example() {
 ### 3. Dùng hook `useT()`
 
 ```tsx
-import { useT } from "@tnet-i18n/i18n";
+import { useT } from "@tnet-store/i18n-stock";
 
 export function Example() {
   const { t, i18n, lng } = useT();
@@ -62,7 +193,7 @@ export function Example() {
     <>
       <p>Current language: {lng}</p>
       <p>{t("common.loading")}</p>
-      <button onClick={() => i18n.changeLanguage(lng === "en" ? "cn" : "en")}>
+      <button onClick={() => i18n.changeLanguage(lng === "en" ? "zh-CN" : "en")}>
         Switch Language
       </button>
     </>
@@ -76,8 +207,10 @@ export function Example() {
 
 ```txt
 locales/
- ├─ en.json   # English
- └─ cn.json   # Chinese
+ ├─ 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`:
@@ -99,11 +232,11 @@ Ví dụ `en.json`:
 
 ## 🔑 Type-safe Keys
 
-Sau mỗi lần build, file `dist/keys.d.ts` sẽ được sinh tự động từ `en.json`.
+Sau mỗi lần build, file `src/__generated__/keys.ts` sẽ được sinh tự động từ `en.json`.
 
 ```ts
-import { t } from "@tnet-i18n/i18n";
-import type { TranslationKey } from "@tnet-i18n/i18n/dist/keys";
+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);
@@ -115,34 +248,38 @@ safeT("button.notExists"); // ❌ lỗi compile
 
 ---
 
-## 🚀 Release quy trình
-
-### 1. Tự động (qua GitHub Actions)
-- Bump version trong `package.json` (ví dụ `"1.0.1"`).
-- Commit & tạo tag theo format:
-  ```bash
-  git commit -am "chore(release): v1.0.1"
-  git tag i18n-v1.0.1
-  git push origin main --tags
-  ```
-- GitHub Actions sẽ tự build & publish lên npm.
-
-### 2. Thủ công (Run workflow)
-- Push code với version mới trong `package.json`.
-- Vào tab **Actions → Publish to npm → Run workflow**.
-- CI sẽ build & publish version mới.
-
----
-
 ## 📦 Scripts có sẵn
 
-- `yarn build` – build TypeScript → `dist/`
+- `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](https://github.com/Trinity-Net-Technology)
+MIT © [Trinity Net Technology](https://github.com/Trinity-Net-Technology)