Skip to content

Commit 0cf6fe5

Browse files
WendellXYWendellXY
committed
chore: revamp README, add icon, bump lib version
Rework project README with new centered header, logo, badges, Quick Start, package/format tables, and clearer AI workflow docs. Update CLI examples (output path, models to gpt-5.4) and add use_tolgee=true in example config. Add docs/langcodec-icon.svg asset. Bump langcodec crate version in langcodec/README.md to 0.10.0 and tidy up links to CLI and library guides.
1 parent d09e2c2 commit 0cf6fe5

3 files changed

Lines changed: 134 additions & 117 deletions

File tree

‎README.md‎

Lines changed: 88 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,109 @@
1-
# langcodec
1+
<p align="center">
2+
<img src="./assets/langcodec-icon.svg" alt="langcodec" width="160" height="160" />
3+
</p>
4+
5+
<h1 align="center">langcodec</h1>
6+
7+
<p align="center">
8+
Universal localization tooling for real product workflows.
9+
</p>
10+
11+
<p align="center">
12+
Convert, inspect, normalize, translate, annotate, and sync localization assets across Apple, Android, CSV, TSV, and Tolgee-backed pipelines.
13+
</p>
14+
15+
<p align="center">
16+
<a href="https://crates.io/crates/langcodec-cli">CLI</a> |
17+
<a href="https://crates.io/crates/langcodec">Library</a> |
18+
<a href="https://docs.rs/langcodec">docs.rs</a> |
19+
<a href="./langcodec-cli/README.md">CLI Guide</a> |
20+
<a href="./langcodec/README.md">Library Guide</a> |
21+
<a href="./CONTRIBUTING.md">Contributing</a>
22+
</p>
23+
24+
<p align="center">
25+
<a href="https://github.com/WendellXY/langcodec/actions/workflows/rust.yml">
26+
<img src="https://img.shields.io/github/actions/workflow/status/WendellXY/langcodec/rust.yml?branch=main&label=ci&logo=github" alt="CI status" />
27+
</a>
28+
<a href="https://crates.io/crates/langcodec-cli">
29+
<img src="https://img.shields.io/crates/v/langcodec-cli?logo=rust" alt="langcodec-cli on crates.io" />
30+
</a>
31+
<a href="https://docs.rs/langcodec">
32+
<img src="https://img.shields.io/docsrs/langcodec?logo=docsdotrs" alt="langcodec docs.rs" />
33+
</a>
34+
</p>
35+
36+
## Why langcodec?
37+
38+
Most localization workflows are a pile of one-off scripts, format-specific tools, spreadsheet exports, and CI glue. `langcodec` gives you one Rust-native toolkit for the loop teams actually run:
39+
40+
- move between Apple, Android, and tabular formats without losing structure
41+
- inspect stale, missing, or incomplete strings before they ship
42+
- normalize files so diffs stay readable in review and CI
43+
- draft translations with AI-backed providers
44+
- generate better translator comments from real source usage
45+
- sync `.xcstrings` catalogs with Tolgee without custom release scripts
246

3-
`langcodec` is a Rust toolkit for working with localization files across Apple, Android, and spreadsheet-style workflows.
4-
5-
It gives you one consistent model for parsing, converting, inspecting, editing, merging, normalizing, and translating files like:
6-
7-
- Apple `.strings`
8-
- Apple `.xcstrings`
9-
- Android `strings.xml`
10-
- CSV
11-
- TSV
47+
## Highlights
1248

13-
This workspace includes:
49+
- Unified data model for singular and plural translations
50+
- Read and write support for Apple `.strings`, Apple `.xcstrings`, Android `strings.xml`, CSV, and TSV
51+
- CLI commands for convert, diff, merge, sync, edit, normalize, view, stats, debug, translate, annotate, and Tolgee sync
52+
- Config-driven AI workflows with `langcodec.toml`
53+
- Rust library API for teams building custom localization pipelines
1454

15-
- `langcodec`: the Rust library crate
16-
- `langcodec-cli`: the `langcodec` command-line tool
55+
## Quick Start
1756

18-
## Why People Use It
57+
Install the CLI:
1958

20-
Localization pipelines usually get messy when teams have to move between iOS, Android, translators, spreadsheets, and CI scripts. `langcodec` is built to reduce that friction.
59+
```sh
60+
cargo install langcodec-cli
61+
```
2162

22-
With one toolchain, you can:
63+
Use the library:
2364

24-
- convert catalogs between Apple, Android, CSV, and TSV
25-
- inspect missing or stale entries
26-
- merge and sync translations safely
27-
- edit files in place across formats
28-
- normalize files to reduce noisy diffs
29-
- generate draft translations with AI-backed providers
30-
- generate translator-facing xcstrings comments from source usage
65+
```toml
66+
[dependencies]
67+
langcodec = "0.10.0"
68+
```
3169

32-
## What It Feels Like
70+
Try the workflow:
3371

3472
```sh
3573
# Convert Apple strings to Android XML
36-
langcodec convert -i Localizable.strings -o strings.xml
74+
langcodec convert -i Localizable.strings -o values/strings.xml
3775

38-
# Inspect untranslated entries
76+
# Inspect work that still needs attention
3977
langcodec view -i Localizable.xcstrings --status new,needs_review --keys-only
4078

41-
# Normalize localization files in CI
79+
# Normalize catalogs in CI
4280
langcodec normalize -i 'locales/**/*.{strings,xml,csv,tsv,xcstrings}' --check
4381

44-
# Draft translations into an .xcstrings catalog
82+
# Draft translations into an existing string catalog
4583
langcodec translate \
4684
--source Localizable.xcstrings \
4785
--source-lang en \
4886
--target-lang fr,de,ja \
4987
--provider openai \
50-
--model gpt-4.1-mini
88+
--model gpt-5.4
5189

52-
# Generate xcstrings comments with source-aware AI annotation
90+
# Generate translator-facing comments from source usage
5391
langcodec annotate \
5492
--input Localizable.xcstrings \
5593
--source-root Sources \
5694
--source-root Modules \
5795
--provider openai \
58-
--model gpt-4.1-mini
59-
```
60-
61-
## Highlights
62-
63-
- Unified data model for singular and plural translations
64-
- Read/write support for Apple, Android, CSV, and TSV formats
65-
- CLI commands for convert, diff, merge, sync, edit, normalize, view, stats, debug, translate, and annotate
66-
- `.xcstrings` and Android plural support
67-
- Config-driven translate and annotate workflows with `langcodec.toml`
68-
- Rust library API for building your own tooling on top
69-
70-
## Installation
71-
72-
Install the CLI:
73-
74-
```sh
75-
cargo install langcodec-cli
96+
--model gpt-5.4
7697
```
7798

78-
Use the library in Rust:
99+
## Packages
79100

80-
```toml
81-
[dependencies]
82-
langcodec = "0.9.1"
83-
```
101+
| Package | What it is | Best for |
102+
| ---------------------------------- | ---------------------- | --------------------------------------------------------------------------- |
103+
| [`langcodec`](./langcodec) | Rust library crate | Building custom localization tooling, validation, and conversions in Rust |
104+
| [`langcodec-cli`](./langcodec-cli) | Command-line interface | Day-to-day conversion, cleanup, translation, annotation, and sync workflows |
84105

85-
## Supported Formats
106+
## Format Support
86107

87108
| Format | Parse | Write | Convert | Merge | Plurals | Comments |
88109
| --------------------- | :---: | :---: | :-----: | :---: | :-----: | :------: |
@@ -92,46 +113,17 @@ langcodec = "0.9.1"
92113
| CSV | yes | yes | yes | yes | no | no |
93114
| TSV | yes | yes | yes | yes | no | no |
94115

95-
## CLI Quick Start
116+
## AI Workflows
96117

97-
### Convert files
98-
99-
```sh
100-
langcodec convert -i input.xcstrings -o output.csv
101-
langcodec convert -i input.csv -o output.xcstrings --source-language en --version 1.0
102-
```
103-
104-
### Inspect work to do
105-
106-
```sh
107-
langcodec view -i Localizable.xcstrings --status new,needs_review
108-
langcodec stats -i Localizable.xcstrings --json
109-
```
110-
111-
### Edit and normalize
112-
113-
```sh
114-
langcodec edit set -i en.strings -k welcome_title -v "Welcome"
115-
langcodec normalize -i values/strings.xml
116-
```
117-
118-
### Merge and sync
119-
120-
```sh
121-
langcodec merge -i a.xcstrings -i b.xcstrings -o merged.xcstrings --strategy last
122-
langcodec sync --source source.xcstrings --target target.xcstrings --match-lang en
123-
```
124-
125-
### AI workflows with config
126-
127-
Create a `langcodec.toml` in your project:
118+
`langcodec` is built for app localization workflows, not just isolated text snippets. `translate` and `annotate` can be driven from a shared `langcodec.toml`, use supported providers such as OpenAI, Anthropic, and Gemini, and scale from a single catalog to config-driven runs across larger repos.
128119

129120
```toml
130121
[openai]
131122
model = "gpt-5.4"
132123

133124
[translate]
134125
concurrency = 4
126+
use_tolgee = true
135127

136128
[translate.input]
137129
source = "locales/Localizable.xcstrings"
@@ -153,15 +145,12 @@ Then run:
153145
```sh
154146
langcodec translate
155147
langcodec annotate
148+
langcodec tolgee pull
156149
```
157150

158-
When exactly one provider section is configured, `translate` and `annotate` use it automatically. If you configure multiple providers, choose one with `--provider` or `translate.provider`. For larger projects, `translate.input.sources = [...]` can fan out parallel runs from config.
151+
For deeper CLI examples, head to [langcodec-cli/README.md](./langcodec-cli/README.md).
159152

160-
`annotate` also supports `annotate.inputs = [...]` for config-driven in-place runs across multiple xcstrings files.
161-
162-
More CLI details live in [langcodec-cli/README.md](langcodec-cli/README.md).
163-
164-
## Library Quick Start
153+
## Rust API
165154

166155
```rust
167156
use langcodec::{Codec, convert_auto};
@@ -180,32 +169,15 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
180169
}
181170
```
182171

183-
The library is a good fit if you want to:
184-
185-
- build custom localization pipelines in Rust
186-
- validate translation assets in CI
187-
- write converters or format-specific tooling
188-
- work with a common representation instead of format-specific parsing code
189-
190-
More library details live in [langcodec/README.md](langcodec/README.md).
191-
192-
## Project Layout
193-
194-
- [langcodec](langcodec): Rust library crate
195-
- [langcodec-cli](langcodec-cli): command-line interface
196-
- [tests](tests): shared test data and integration coverage
197-
198-
## Current Status
199-
200-
The current release is `0.10.0` on [crates.io](https://crates.io/crates/langcodec). It is already useful in real workflows, but it is still a `0.x` project, so APIs and behavior may continue to evolve.
201-
202-
## Contributing
172+
The library is a good fit if you want to build custom pipelines, validate assets in CI, or work with a consistent representation instead of format-specific parsers.
203173

204-
Issues, ideas, and pull requests are welcome.
174+
## Documentation
205175

206-
- Project roadmap: [ROADMAP.md](ROADMAP.md)
207-
- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
176+
- [CLI guide](./langcodec-cli/README.md)
177+
- [Library guide](./langcodec/README.md)
178+
- [Contribution guide](./CONTRIBUTING.md)
179+
- [Project roadmap](./ROADMAP.md)
208180

209181
## License
210182

211-
MIT
183+
[MIT](./LICENSE)

‎assets/langcodec-icon.svg‎

Lines changed: 45 additions & 0 deletions
Loading

‎langcodec/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Universal localization file toolkit for Rust. Parse, write, convert, merge.
1010

1111
```toml
1212
[dependencies]
13-
langcodec = "0.9.1"
13+
langcodec = "0.10.0"
1414
```
1515

1616
Docs: <https://docs.rs/langcodec>

0 commit comments

Comments
 (0)