readme-i18n-sentinel

English | 日本語 | 简体中文 | Español | Português | 한국어 | Français | Deutsch | Русский | हिन्दी | العربية | 繁體中文

一個驗證來源與翻譯版README檔案之間結構一致性的CLI工具。

What it does

比較您的源 README 與翻譯版本，確保它們具有相同的結構：

• 章節數量和層次結構 - 相同級別的相同數量標題
• 行位置 - 章節從相同的行號開始
• 行數 - 檔案具有相同的總行數
• 章節標題（可選）- 標題保持原始語言
• 程式碼區塊（可選）- 程式碼範例保持不變

範例： 如果您的英文 README 有 5 個章節和 150 行，但日文版本有 4 個章節和 140 行，該工具將檢測到這種不匹配，並報告缺少或未對齊的章節。

Installation

要求： Node.js v20 或更高版本

# Global installation (recommended)
npm install -g readme-i18n-sentinel

# Project-specific installation
npm install --save-dev readme-i18n-sentinel

# Or use directly with npx
npx readme-i18n-sentinel

Quick Start

# Just run without any arguments - it will auto-detect README files
readme-i18n-sentinel

# Automatically checks:
# - Source: README.md
# - Targets: README.*.md, docs/README.*.md, docs/*/README.md, docs/*/README.*.md

Usage

Options

• -s, --source <path> - 源 README 檔案路徑 (default: README.md)
• -t, --target <pattern> - 目標檔案模式（支援 glob）(default: {README.*.md,docs/README.*.md,docs/*/README.md,docs/*/README.*.md})
• --skip-section-structure-check - 跳過標題數量和層次結構驗證（# vs ##）
• --skip-line-count-check - 跳過總行數和標題行位置驗證
• --require-original-section-titles - 要求標題文字完全匹配（例如，"## Installation" 必須保持英文）
• --require-original-code-blocks - 要求程式碼區塊完全匹配（包括 ``` 內的內容）
• --json - 以 JSON 格式輸出結果，用於 CI/CD 整合

Examples

# Basic usage with auto-detection
readme-i18n-sentinel

# JSON output for CI/CD
readme-i18n-sentinel --json

# Custom paths
readme-i18n-sentinel --source docs/README.md --target "docs/README.*.md"

Integration

Husky (Git Hooks)

簡單版本 - 每次提交時檢查翻譯：

# .husky/pre-commit

npx readme-i18n-sentinel

進階版本 - 僅在修改 README.md 時檢查並支援跳過標記：

# .husky/commit-msg

README_FILE='README.md'
I18N_SKIP_FLAG='[i18n-skip]'

if git diff --cached --name-only | grep -q "^${README_FILE}$"; then
  if ! grep -qF "${I18N_SKIP_FLAG}" "$1"; then
    if ! npx readme-i18n-sentinel; then
      echo "❌ README translation check failed"
      echo "Please fix the issues above or add '${I18N_SKIP_FLAG}' to your commit message to skip this check."
      echo "Example: feat: update documentation ${I18N_SKIP_FLAG}"
      exit 1
    fi
  else
    echo "📖 Skipping README translation check due to ${I18N_SKIP_FLAG} flag"
  fi
fi

要臨時跳過檢查（僅進階版本），請在提交訊息中添加 [i18n-skip]：

git commit -m "feat: urgent fix [i18n-skip]"

CI/CD

# GitHub Actions
- name: Check README translations
  run: npx readme-i18n-sentinel

# GitLab CI
check-translations:
  script: npx readme-i18n-sentinel

Contributing

歡迎貢獻！請隨時提交 Pull Request。

License

MIT