Skip to content

Commit d6fbdde

Browse files
WendellXYWendellXY
committed
Add crate-specific READMEs and update main README
Introduced separate README.md files for the langcodec library and langcodec-cli CLI tool, each with focused usage and documentation. Updated the main README.md to provide a concise overview and direct users to the appropriate crate-specific guides. Also updated Cargo.toml files to reference the correct local README for each crate.
1 parent d44458b commit d6fbdde

5 files changed

Lines changed: 179 additions & 180 deletions

File tree

‎README.md‎

Lines changed: 43 additions & 178 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,31 @@
11
# langcodec
22

3-
**A universal localization file toolkit in Rust.**
3+
Universal localization toolkit: library + CLI for Apple/Android/CSV/TSV.
44

5-
`langcodec` provides format-agnostic parsing, conversion, merging, and serialization for major localization formats, including Apple `.strings`, `.xcstrings`, Android `strings.xml`, CSV, and TSV. It enables seamless conversion and merging between formats, powerful internal data modeling, and extensibility for new formats.
5+
- Library crate (`langcodec`): parse, write, convert, merge with a unified model
6+
- CLI crate (`langcodec-cli`): convert, merge, view, stats, debug
67

78
---
89

910
## Status
1011

11-
This is a `0.4.0` release available on [crates.io](https://crates.io/crates/langcodec). As a 0.x version, the API may evolve as development continues. The library is functional and well-tested, but breaking changes may occur in future releases. Contributions and feedback are very welcome to help shape the future of this project!
12+
This is a `0.4.0` release available on [crates.io](https://crates.io/crates/langcodec). As a 0.x version, APIs may evolve. Contributions and feedback are very welcome!
1213

1314
---
1415

1516
## Installation
1617

17-
### CLI Tool
18-
19-
Install the command-line interface from crates.io:
20-
21-
```sh
22-
cargo install langcodec-cli
23-
```
24-
25-
### Library
26-
27-
Add to your `Cargo.toml`:
28-
29-
```toml
30-
[dependencies]
31-
langcodec = "0.4.0"
32-
```
18+
- CLI: `cargo install langcodec-cli`
19+
- Lib: add `langcodec = "0.4.0"` to your `Cargo.toml`
3320

3421
---
3522

3623
## Features
3724

38-
- ✨ Parse, write, convert, and merge multiple localization file formats
39-
- 🦀 Idiomatic, modular, and ergonomic Rust API
40-
- 📦 Designed for CLI tools, CI/CD pipelines, and library integration
41-
- 🔄 Unified internal model (`Resource`) for lossless format-agnostic processing
42-
- 📖 Well-documented, robust error handling and extensible codebase
43-
- 🚀 More formats and CLI support are planned for upcoming releases
25+
- Parse, write, convert, merge: `.strings`, `.xcstrings`, `strings.xml`, CSV, TSV
26+
- Unified `Resource` model (`Translation::Singular|Plural`)
27+
- Plurals: `.xcstrings` and Android `<plurals>` supported
28+
- CLI helpers: convert, merge, view, stats (JSON or human-readable)
4429

4530
---
4631

@@ -62,103 +47,39 @@ langcodec = "0.4.0"
6247

6348
---
6449

65-
## Usage
66-
67-
### As a Library
68-
69-
Add to your `Cargo.toml`:
70-
71-
```toml
72-
[dependencies]
73-
langcodec = "0.4.0"
74-
```
75-
76-
#### Example: Read, Manipulate, and Write
77-
78-
```rust
79-
use langcodec::{Codec, formats::FormatType};
80-
81-
fn main() -> Result<(), Box<dyn std::error::Error>> {
82-
let mut codec = Codec::new();
83-
84-
// Read Apple .strings file
85-
codec.read_file_by_extension("en.lproj/Localizable.strings", None)?;
50+
## Getting Started
8651

87-
// Manipulate resources if needed (see types.rs for Resource/Entry APIs)
88-
89-
// Write changes back to the original file
90-
codec.write_to_file()?;
91-
92-
// Convert Apple's strings localization to Android's strings
93-
convert_auto("Localizable.strings", "strings.xml")?;
94-
95-
Ok(())
96-
}
97-
```
52+
- Library guide: see `langcodec/README.md`
53+
- CLI guide: see `langcodec-cli/README.md`
9854

9955
---
10056

101-
### CLI
102-
103-
A CLI tool is provided for easy conversion, merging, and debugging of localization files.
104-
105-
#### Install
106-
107-
```sh
108-
# From crates.io (recommended)
109-
cargo install langcodec-cli
110-
111-
# From source
112-
cargo install --path langcodec-cli
113-
```
114-
115-
#### Commands
116-
117-
- **Convert** between formats:
118-
119-
```sh
120-
langcodec convert -i input.strings -o output.xml
121-
langcodec convert -i input.csv -o output.strings
122-
langcodec convert -i input.tsv -o output.xcstrings
123-
langcodec convert -i input.json -o output.xcstrings
124-
# Override xcstrings metadata
125-
langcodec convert -i input.json -o output.xcstrings --source-language en-GB --version 2.0
126-
```
127-
128-
The convert command automatically detects input and output formats from file extensions.
129-
For JSON files, it will try multiple parsing strategies:
130-
- Standard Resource format (if supported by langcodec)
131-
- JSON key-value pairs (for custom JSON formats)
57+
### CLI Highlights
13258

133-
- **Merge** multiple files of the same format:
134-
135-
```sh
136-
langcodec merge -i file1.csv file2.csv -o merged.csv --lang en --strategy last
137-
langcodec merge -i file1.tsv file2.tsv -o merged.tsv --lang en --strategy last
138-
langcodec merge -i en.lproj/Localizable.strings fr.lproj/Localizable.strings -o merged.strings --lang en
139-
```
140-
141-
- `--strategy` can be `last` (default), `first`, or `error` (fail on conflict).
142-
- `--lang` is required for formats that need a language code (e.g., CSV, .strings).
143-
- For `.xcstrings` output, you can override metadata:
144-
- `--source-language` (default: `en`)
145-
- `--version` (default: `1.0`)
146-
147-
- **Debug**: Output a file's parsed representation as JSON:
148-
149-
```sh
150-
langcodec debug -i input.csv --lang en
151-
langcodec debug -i input.tsv --lang en
152-
langcodec debug -i input.strings --lang en -o output.json
153-
```
154-
155-
- **View**: Pretty-print entries in a localization file:
156-
157-
```sh
158-
langcodec view -i input.strings --lang en
159-
langcodec view -i input.tsv --lang en
160-
langcodec view -i strings.xml --full # Displays "Type: Plural" for Android plurals
161-
```
59+
- Convert: `langcodec convert -i input.strings -o strings.xml`
60+
- View: `langcodec view -i strings.xml --full`
61+
- Stats (JSON): `langcodec stats -i Localizable.xcstrings --json`
62+
- See full options: langcodec-cli/README.md#stats
63+
- Example output:
64+
```json
65+
{
66+
"summary": { "languages": 1, "unique_keys": 42 },
67+
"languages": [
68+
{
69+
"language": "en",
70+
"total": 42,
71+
"by_status": {
72+
"translated": 30,
73+
"needs_review": 2,
74+
"stale": 0,
75+
"new": 10,
76+
"do_not_translate": 0
77+
},
78+
"completion_percent": 75.0
79+
}
80+
]
81+
}
82+
```
16283

16384
#### Notes
16485

@@ -175,76 +96,20 @@ cargo install --path langcodec-cli
17596
- `.xcstrings` plural variations convert to Android `<plurals>` when targeting Android output.
17697
- The `view` command prints plural entries with a "Type: Plural" header and each category/value.
17798

178-
#### Custom Formats
179-
180-
The CLI supports additional custom formats for specialized use cases:
181-
182-
**JSON Language Map** (`json-language-map`):
183-
184-
```json
185-
{
186-
"key": "hello_world",
187-
"en": "Hello, World!",
188-
"fr": "Bonjour, le monde!"
189-
}
190-
```
191-
192-
**JSON Array Language Map** (`json-array-language-map`):
193-
194-
<!-- cspell:disable -->
195-
```json
196-
[
197-
{
198-
"key": "hello_world",
199-
"en": "Hello, World!",
200-
"fr": "Bonjour, le monde!"
201-
},
202-
{
203-
"key": "welcome_message",
204-
"en": "Welcome to our app!",
205-
"fr": "Bienvenue dans notre application!"
206-
}
207-
]
208-
```
209-
<!-- cspell:enable -->
210-
211-
**YAML Language Map** (`yaml-language-map`):
212-
213-
```yaml
214-
key: hello_world
215-
en: Hello, World!
216-
fr: Bonjour, le monde!
217-
```
218-
219-
Use these formats with the `--input-format` flag:
220-
221-
```sh
222-
langcodec convert -i input.json -o output.xcstrings --input-format json-language-map
223-
langcodec convert -i input.json -o output.xcstrings --input-format json-array-language-map
224-
langcodec convert -i input.yaml -o output.xcstrings --input-format yaml-language-map
225-
```
99+
For JSON/YAML custom formats and more examples, see `langcodec-cli/README.md`.
226100

227101
---
228102

229103
## Data Model
230104

231-
At the core of `langcodec` is the `Resource` struct—an expressive, format-agnostic model for localization data.
232-
See [`src/types.rs`](src/types.rs) for details.
233-
234-
```rust
235-
pub struct Resource {
236-
pub metadata: Metadata,
237-
pub entries: Vec<Entry>,
238-
}
239-
```
240-
241-
Each `Entry` supports singular and plural translations, comments, status, and custom fields.
105+
At the core is the `Resource` struct with `Entry` values (singular or plural). See `langcodec/README.md` and docs.rs for details.
242106

243107
---
244108

245-
## Error Handling
109+
## Roadmap & Contributing
246110

247-
All public APIs use the crate's own `Error` enum, which provides meaningful variants for parsing, I/O, and format mismatches.
111+
- Roadmap: see `ROADMAP.md`
112+
- Contributions welcome! Please open issues/PRs.
248113

249114
---
250115

‎langcodec-cli/Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description = "A universal CLI tool for converting and inspecting localization f
66
license = "MIT"
77
repository = "https://github.com/WendellXY/langcodec"
88
homepage = "https://github.com/WendellXY/langcodec"
9-
readme = "../README.md"
9+
readme = "README.md"
1010
keywords = ["localization", "i18n", "cli", "android", "apple"]
1111
categories = ["command-line-utilities", "internationalization", "localization"]
1212
documentation = "https://docs.rs/langcodec-cli"

‎langcodec-cli/README.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# langcodec-cli (Command Line)
2+
3+
Universal CLI for converting, inspecting, and merging localization files.
4+
5+
- Formats: Apple `.strings`, `.xcstrings`, Android `strings.xml`, CSV, TSV
6+
- Commands: convert, merge, view, stats, debug
7+
8+
## Install
9+
10+
```sh
11+
cargo install langcodec-cli
12+
```
13+
14+
## Commands
15+
16+
### convert
17+
18+
```sh
19+
langcodec convert -i input.strings -o strings.xml
20+
langcodec convert -i input.csv -o output.xcstrings --source-language en --version 1.0
21+
```
22+
23+
Auto-detects formats from extensions. For JSON/YAML custom formats, see `--input-format` in the root README.
24+
25+
### merge
26+
27+
```sh
28+
langcodec merge -i a.strings -i b.strings -o merged.strings --lang en --strategy last
29+
```
30+
31+
### view
32+
33+
```sh
34+
langcodec view -i values/strings.xml --full
35+
```
36+
37+
Prints entries. Plurals are labeled with `Type: Plural` and show categories.
38+
39+
### stats
40+
41+
```sh
42+
langcodec stats -i values/strings.xml
43+
langcodec stats -i Localizable.xcstrings --json
44+
```
45+
46+
Shows per-language totals, counts by status, and completion percent (excludes DoNotTranslate). Use `--json` for machine-readable output.
47+
48+
### debug
49+
50+
```sh
51+
langcodec debug -i input.strings --lang en -o output.json
52+
```
53+
54+
## Notes
55+
56+
- Android plurals `<plurals>` are supported.
57+
- Language inference: `en.lproj/Localizable.strings`, `values-es/strings.xml`, base `values/` → `en` by default.
58+
- Globbing: use quotes for patterns in merge (e.g., `'**/*.xml'`).
59+
60+
## License
61+
62+
MIT

‎langcodec/Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ license = "MIT"
77
repository = "https://github.com/WendellXY/langcodec"
88
homepage = "https://github.com/WendellXY/langcodec"
99
documentation = "https://docs.rs/langcodec"
10-
readme = "../README.md"
10+
readme = "README.md"
1111
keywords = ["localization", "i18n", "l10n", "android", "apple"]
1212
categories = ["internationalization", "localization", "encoding"]
1313

0 commit comments

Comments
 (0)