docs: add commit message style guidelines to CONTRIBUTING.md

WendellXY · WendellXY · commit fba3618bd347 · 2025-09-03T02:26:04.000+08:00
- Introduced a section outlining the Conventional Commits specification for commit messages.
- Provided examples and detailed formatting rules to enhance clarity and consistency in commit history.
- Updated the example commit command to reflect the new format.
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,244 @@
+# AGENTS.md — Automation and Navigation Guide
+
+This document helps automation agents quickly understand, build, test, and operate this repository.
+
+## Overview
+
+- **Library crate**: `langcodec/` — universal localization toolkit (parse/convert Apple `.strings`, `.xcstrings`, Android `strings.xml`, CSV, TSV)
+- **CLI crate**: `langcodec-cli/` — end-user command-line tool built on the library
+- **Binary name**: `langcodec`
+
+## Repository layout (key paths)
+
+- `langcodec/src/lib.rs`: library entry; re-exports `Codec`, `convert_auto`, `FormatType`, `types::*`
+- `langcodec/src/formats/`: parsers/writers for `strings`, `xcstrings`, `android_strings`, `csv`, `tsv`
+- `langcodec/src/traits.rs`: `Parser` trait for format-agnostic IO
+- `langcodec-cli/src/main.rs`: CLI entry with subcommands
+- `langcodec-cli/src/transformers/`: one-way converters for custom JSON/YAML formats
+- `langcodec-cli/tests/` and `langcodec-cli/tests/fixtures/`: integration tests and sample inputs
+
+## Prerequisites
+
+- Rust toolchain with Edition 2024 support (install via rustup)
+- macOS/Linux shell environment for examples below
+
+Optional tooling for contributors:
+
+- `cargo fmt`, `cargo clippy`
+
+## Absolute path convention in this guide
+
+Replace `<repo>` with the absolute path to the repository root. Example:
+
+```bash
+REPO="/Users/wendell/Developer/langcodec"
+```
+
+When running commands non-interactively, prefer absolute paths like `"$REPO/target/release/langcodec"` and explicit input/output file paths.
+
+## Build
+
+```bash
+cd "$REPO"
+cargo build --release -p langcodec-cli
+```
+
+- Output binary: `"$REPO/target/release/langcodec"`
+
+Build just the library:
+
+```bash
+cargo build --release -p langcodec
+```
+
+## Test
+
+```bash
+cd "$REPO"
+cargo test --all
+```
+
+Run only CLI tests:
+
+```bash
+cargo test -p langcodec-cli
+```
+
+## CLI quick reference
+
+Binary: `"$REPO/target/release/langcodec"`
+
+- `convert`: Convert localization files between formats (auto-detect by extension)
+- `edit set`: Add/update/remove entries in-place (or to `--output`)
+- `view`: Pretty-print entries, filter by `--lang`, optional `--check_plurals`
+- `merge`: Merge multiple inputs to one output with conflict strategy
+- `stats`: Coverage and per-status counts (text or `--json`)
+- `debug`: Read file and emit JSON (to stdout or `--output`)
+- `completions`: Generate shell completion scripts
+
+Show help for any subcommand:
+
+```bash
+"$REPO/target/release/langcodec" --help | cat
+"$REPO/target/release/langcodec" convert --help | cat
+```
+
+## Supported formats
+
+Standard (read/write):
+
+- **Apple**: `.strings`, `.xcstrings`
+- **Android**: `strings.xml`
+- **CSV**, **TSV**
+
+Custom inputs (one-way into internal Resources via CLI):
+
+- `json-language-map`, `json-array-language-map`, `yaml-language-map`, `langcodec-resource-array` (`.langcodec`)
+
+## Common automation recipes (absolute paths)
+
+- Convert `.strings` → Android XML:
+
+```bash
+"$REPO/target/release/langcodec" convert \
+  --input "/abs/path/Localizable.strings" \
+  --output "/abs/path/values/strings.xml"
+```
+
+- Convert `.xcstrings` → CSV:
+
+```bash
+"$REPO/target/release/langcodec" convert \
+  --input "/abs/path/Localizable.xcstrings" \
+  --output "/abs/path/translations.csv"
+```
+
+- Convert custom JSON language map → `.xcstrings` with overrides:
+
+```bash
+"$REPO/target/release/langcodec" convert \
+  --input "/abs/path/translations.json" \
+  --output "/abs/path/Localizable.xcstrings" \
+  --input_format json-language-map \
+  --output_format xcstrings \
+  --source_language en \
+  --version 1.0
+```
+
+- Edit in place (add/update). For single-language formats, specify `--lang` as needed:
+
+```bash
+"$REPO/target/release/langcodec" edit set \
+  --inputs "/abs/path/en.lproj/Localizable.strings" \
+  --lang en \
+  --key welcome_message \
+  --value "Hello, World!"
+```
+
+- Remove a key (omit or empty `--value`):
+
+```bash
+"$REPO/target/release/langcodec" edit set \
+  --inputs "/abs/path/values/strings.xml" \
+  --lang en \
+  --key obsolete_key \
+  --value ""
+```
+
+- Preview changes without writing:
+
+```bash
+"$REPO/target/release/langcodec" edit set \
+  --inputs "/abs/path/en.lproj/Localizable.strings" \
+  --lang en \
+  --key welcome_message \
+  --value "Hello" \
+  --dry_run
+```
+
+- View entries (full values) and check plurals:
+
+```bash
+"$REPO/target/release/langcodec" view \
+  --input "/abs/path/Localizable.xcstrings" \
+  --lang en \
+  --full \
+  --check_plurals
+```
+
+- Merge multiple files (quote globs to avoid shell-side expansion):
+
+```bash
+"$REPO/target/release/langcodec" merge \
+  --inputs "/abs/path/**/Localizable.strings" \
+  --output "/abs/path/merged.xcstrings" \
+  --strategy last \
+  --lang en \
+  --source_language en \
+  --version 1.0
+```
+
+- Stats (machine-readable):
+
+```bash
+"$REPO/target/release/langcodec" stats \
+  --input "/abs/path/Localizable.xcstrings" \
+  --lang en \
+  --json
+```
+
+- Debug (emit JSON to file):
+
+```bash
+"$REPO/target/release/langcodec" debug \
+  --input "/abs/path/values/strings.xml" \
+  --lang en \
+  --output "/abs/path/out.json"
+```
+
+## Exit codes (for CI/non-interactive use)
+
+- `0`: success
+- `1`: validation or runtime failure (e.g., invalid inputs, unsupported format)
+- `2`: plural validation failed (when `view --check_plurals` is used)
+
+## Behavior notes for agents
+
+- All commands are non-interactive. Always pass explicit absolute paths.
+- Input/output formats are inferred from file extensions unless `--input_format` / `--output_format` is provided.
+- For single-language formats, pass `--lang` when required (e.g., ambiguous inputs).
+- Quote glob patterns provided to `merge --inputs` to avoid slow shell-side expansion.
+
+## Library usage (Rust)
+
+The library exposes a high-level API. Minimal example:
+
+```rust
+use langcodec::convert_auto;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    convert_auto("/abs/path/Localizable.strings", "/abs/path/values/strings.xml")?;
+    Ok(())
+}
+```
+
+Builder pattern and direct `Codec` manipulation are also available; see `langcodec/src/lib.rs` for more examples and re-exports.
+
+## Extension points (for contributors/agents)
+
+- Add/modify formats: edit files under `langcodec/src/formats/` and wire into `formats/mod.rs`
+- Implement parsing/writing: implement `Parser` in `langcodec/src/traits.rs`
+- Add CLI subcommands/options: edit `langcodec-cli/src/main.rs` and corresponding modules
+- Support new custom one-way formats: add a transformer under `langcodec-cli/src/transformers/` and register in `transformers/mod.rs` and `formats.rs`
+
+## Reproducible CI example
+
+```bash
+set -euo pipefail
+REPO="/abs/path/to/langcodec"
+cargo build --release -p langcodec-cli --manifest-path "$REPO/Cargo.toml"
+"$REPO/target/release/langcodec" --version | cat
+"$REPO/target/release/langcodec" convert \
+  --input "/abs/path/Localizable.xcstrings" \
+  --output "/abs/path/translations.csv"
+```
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -58,6 +58,38 @@ To add support for a new localization format:
 - Add examples in doc comments
 - Update the format support table in README.md
 
+## Commit message style
+
+Follow the Conventional Commits specification to keep history readable and enable automated changelog tooling. See the official docs: <https://www.conventionalcommits.org/en/v1.0.0/>.
+
+- Use the format: `<type>(<scope>): <subject>`
+- type: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+- scope (optional): one of lib, cli, formats, formats/android, formats/strings, formats/xcstrings, formats/csv, formats/tsv, transformers, validation, docs, tests
+- subject: imperative mood, lowercase, ≤ 72 characters, no trailing period
+- Separate body from subject with a blank line; explain motivation and impact
+- Reference issues in the body or footer (e.g., Refs #123 or Fixes #123)
+- Breaking changes: use `feat!:` or `fix!:` in the subject, and include a `BREAKING CHANGE:` footer
+
+Examples:
+
+```text
+feat(cli): add --check_plurals to view command
+
+fix(formats/android): escape apostrophes correctly in strings.xml
+
+refactor(lib): simplify plural rules evaluation
+
+chore: update dependencies
+
+feat!: replace plural category API
+
+feat(cli): add stats --json output
+
+Provide machine-readable stats for CI consumers and human-readable summary by default.
+
+BREAKING CHANGE: stats subcommand no longer prints totals by default; use --json.
+```
+
 ## Submitting Changes
 
 **1. Create a feature branch:**
@@ -70,7 +102,7 @@ To add support for a new localization format:
 
  ```bash
  git add .
- git commit -m "Add: brief description of changes"
+ git commit -m "feat: brief description of changes"
  ```
 
 **3. Push and create a pull request:**
diff --git a/langcodec-cli/src/edit.rs b/langcodec-cli/src/edit.rs
@@ -132,14 +132,14 @@ pub fn run_edit_set_command(opts: EditSetOptions) -> Result<(), String> {
         }
         processed_count += 1;
         // Validate per-file
-        let mut vctx = ValidationContext::new().with_input_file(input_path.clone());
+        let mut validation_context = ValidationContext::new().with_input_file(input_path.clone());
         if let Some(l) = &opts.lang {
-            vctx = vctx.with_language_code(l.clone());
+            validation_context = validation_context.with_language_code(l.clone());
         }
         if let Some(o) = &opts.output {
-            vctx = vctx.with_output_file(o.clone());
+            validation_context = validation_context.with_output_file(o.clone());
         }
-        if let Err(e) = validate_context(&vctx) {
+        if let Err(e) = validate_context(&validation_context) {
             let msg = format!("Input validation failed for '{}': {}", input_path, e);
             if opts.continue_on_error {
                 eprintln!("❌ {}", msg);
@@ -273,7 +273,7 @@ fn apply_set_to_file(
         }
     } else {
         let resolved_lang_owned: String;
-        let lref: &str = if let Some(l) = lang.as_deref() {
+        let lang_ref: &str = if let Some(l) = lang.as_deref() {
             l
         } else if codec.resources.len() == 1 {
             resolved_lang_owned = codec.resources[0].metadata.language.clone();
@@ -285,10 +285,10 @@ fn apply_set_to_file(
             ));
         };
         let val = value.clone().unwrap_or_default();
-        let exists = codec.has_entry(key, lref);
+        let exists = codec.has_entry(key, lang_ref);
         if exists {
             let old = codec
-                .find_entry(key, lref)
+                .find_entry(key, lang_ref)
                 .map(|e| match &e.value {
                     Translation::Singular(s) => s.clone(),
                     Translation::Plural(p) => p.id.clone(),
@@ -297,40 +297,40 @@ fn apply_set_to_file(
             if dry_run {
                 println!(
                     "DRY-RUN: Would update '{}' in {}: '{}' -> '{}' ({})",
-                    key, lref, old, val, input
+                    key, lang_ref, old, val, input
                 );
             } else {
                 codec
                     .update_translation(
                         key,
-                        lref,
+                        lang_ref,
                         Translation::Singular(val.clone()),
                         status_parsed.clone(),
                     )
                     .map_err(|e| e.to_string())?;
                 if comment.is_some()
-                    && let Some(entry) = codec.find_entry_mut(key, lref)
+                    && let Some(entry) = codec.find_entry_mut(key, lang_ref)
                 {
                     entry.comment = comment.clone();
                 }
-                println!("✅ Updated '{}' in {} ({})", key, lref, input);
+                println!("✅ Updated '{}' in {} ({})", key, lang_ref, input);
             }
         } else if dry_run {
             println!(
                 "DRY-RUN: Would add '{}' to {} with value '{}' ({})",
-                key, lref, val, input
+                key, lang_ref, val, input
             );
         } else {
             codec
                 .add_entry(
                     key,
-                    lref,
+                    lang_ref,
                     Translation::Singular(val.clone()),
                     comment.clone(),
                     status_parsed.clone(),
                 )
                 .map_err(|e| e.to_string())?;
-            println!("✅ Added '{}' to {} ({})", key, lref, input);
+            println!("✅ Added '{}' to {} ({})", key, lang_ref, input);
         }
     }
 
