app-localizer 1.0.1__tar.gz

app_localizer-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle Hughes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

app_localizer-1.0.1/PKG-INFO

@@ -0,0 +1,425 @@
+Metadata-Version: 2.4
+Name: app-localizer
+Version: 1.0.1
+Summary: Translate Apple String Catalogs and Fastlane App Store metadata.
+Author: Kyle Hughes
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kylehughes/app-localizer
+Project-URL: Repository, https://github.com/kylehughes/app-localizer
+Project-URL: Changelog, https://github.com/kylehughes/app-localizer/blob/main/CHANGELOG.md
+Keywords: localization,i18n,xcstrings,fastlane,app-store,translation,openai
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Localization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Dynamic: license-file
+
+# App Localizer
+
+[![Test](https://github.com/kylehughes/app-localizer/actions/workflows/ci.yml/badge.svg)](https://github.com/kylehughes/app-localizer/actions/workflows/ci.yml)
+
+*Translate Xcode String Catalogs (`.xcstrings`) and Fastlane App Store metadata from the command line with any OpenAI-compatible chat completions endpoint.*
+
+## About
+
+App Localizer is a development and CI tool for app repositories. It edits localization inputs in place, records what it generated, and skips unchanged work on later runs.
+
+The output is a translation draft. It still belongs in code review, especially UI, legal text, purchase flows, and App Store copy. Do not ship App Localizer in an app target, call it from app code, or put provider API keys in mobile apps.
+
+### Supported Inputs
+
+Two input types are supported, configured independently:
+
+- **String Catalogs.** Fills missing or untranslated `.xcstrings` entries. Preserves placeholders, substitutions, variation trees, translator comments, and localizations outside the current run.
+- **Fastlane metadata.** Translates `fastlane/metadata/<locale>/*.txt` App Store copy, copies URL fields verbatim, and enforces App Store character limits.
+
+## Quick Start
+
+### Installation
+
+Install the CLI from PyPI:
+
+```sh
+uv tool install app-localizer
+```
+
+`pipx install app-localizer` and `python3 -m pip install app-localizer` work too. Pin a version for reproducible installs:
+
+```sh
+uv tool install "app-localizer==1.0.1"
+```
+
+### Configuration
+
+Add `app-localizer.toml` to the app repository root with the sections the repository needs:
+
+```toml
+[xcstrings]
+sources = ["App/Resources/Localizable.xcstrings"]
+languages = ["de", "es", "fr", "ja"]
+
+[fastlane]
+metadata_path = "fastlane/metadata"
+source_locale = "en-US"
+locales = ["de-DE", "es-ES", "fr-FR", "ja"]
+```
+
+Paths resolve relative to the config file, so the same config works from CI and local shells when `--config` points at it.
+
+### First Run
+
+Validate the config and file structure without a provider API key:
+
+```sh
+app-localizer --check
+```
+
+Preview pending translation work without writing files:
+
+```sh
+app-localizer --dry-run
+```
+
+Translate configured inputs:
+
+```sh
+export OPENAI_API_KEY=...
+app-localizer
+```
+
+A run rewrites catalogs and metadata in place, then updates `.app-localizer.lock` files. Commit the config, generated localization files, metadata, and lockfiles. Do not commit API keys or `app-localizer.secrets.toml`.
+
+## Command-Line Interface
+
+### Common Commands
+
+Run these from the app repository root unless passing `--config`:
+
+```sh
+# Validate config, catalogs, metadata, and existing generated files.
+app-localizer --check
+
+# Show pending work without network access or file writes.
+app-localizer --dry-run
+
+# Translate every configured domain.
+app-localizer
+
+# Process one configured domain.
+app-localizer --domain fastlane
+
+# Retranslate even values already marked translated or locked.
+app-localizer --force
+```
+
+`--check` and `--dry-run` do not require an API key. `--fail-on-untranslated` makes either command exit nonzero while work is pending. It is additive: a run can enable the policy, but cannot disable `fail_on_untranslated = true` set in the config.
+
+### Options
+
+`--config` selects a config file. Without it, the CLI reads `app-localizer.toml` from the working directory when that file exists.
+
+Provider overrides are run-specific: `--base-url`, `--model`, `--reasoning-effort`, `--temperature`, and `--candidates`. `--api-key` supplies a provider key directly and wins over environment variables and the secrets file. `--secrets` selects a different TOML secrets file.
+
+`--verbose` enables debug logging. `--version` prints the installed package version. `app-localizer --help` prints the full parser output.
+
+### Ad Hoc Catalog Runs
+
+For one-off String Catalog translation without a config file, pass catalog paths and target languages directly:
+
+```sh
+app-localizer --source Localizable.xcstrings --languages de es fr
+```
+
+Ad hoc runs configure only the String Catalog domain. Use a config file for repeatable app-team workflows.
+
+## Configuration Reference
+
+All non-secret settings live in `app-localizer.toml`. Unknown keys are rejected, so typos fail early. See [examples/app-localizer.toml](examples/app-localizer.toml) for a copyable template.
+
+### Provider Settings
+
+Provider settings are top-level and shared by both domains:
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `base_url` | `https://api.openai.com/v1` | OpenAI-compatible chat completions endpoint. |
+| `api_key_env` | `OPENAI_API_KEY` | Environment variable holding the API key. Set to `""` for keyless local endpoints. |
+| `model` | `gpt-5.2` | Model identifier to request from the endpoint. |
+| `reasoning_effort` | unset | Optional reasoning effort: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. Unsupported endpoints are retried without it for the rest of the run. |
+| `temperature` | `0.2` | Sampling temperature for translation requests. |
+| `candidates` | `3` | Candidate translations requested per value before the decider pass chooses one. |
+| `fail_on_untranslated` | `false` | Makes `--check` and `--dry-run` fail while anything is pending. |
+
+### String Catalogs
+
+`[xcstrings]` enables `.xcstrings` translation:
+
+| Key | Description |
+| --- | --- |
+| `sources` | Catalog paths, resolved relative to the config file. |
+| `languages` | Target Xcode language tags, for example `de`, `pt-BR`, `zh-Hans`. |
+
+### Fastlane Metadata
+
+`[fastlane]` enables App Store metadata translation:
+
+| Key | Description |
+| --- | --- |
+| `metadata_path` | Fastlane metadata directory, resolved relative to the config file. |
+| `source_locale` | Locale directory to translate from, for example `en-US`. Fastlane's `default` fallback directory also works. |
+| `locales` | Target App Store Connect locales, for example `de-DE`, `fr-FR`. Typos like `de` fail validation. |
+| `keywords_trim_to_fit` | Defaults to `true`. Generated `keywords.txt` translations are normalized, deduplicated case-insensitively, and trimmed from the tail until the comma-joined list fits 100 characters. Set to `false` to reject over-limit keyword translations instead. |
+| `allow_unknown_locales` | Defaults to `false`. Set to `true` to accept App Store locales added after this package's release instead of failing validation. Unknown locales warn; malformed tags still fail. |
+
+### Secrets
+
+API keys do not belong in `app-localizer.toml`. Resolution order is `--api-key`, then the environment variable named by `api_key_env`, then the secrets file. `--secrets` selects a different file.
+
+Use an environment variable for individual developer machines:
+
+```sh
+export OPENAI_API_KEY=...
+app-localizer
+```
+
+Teams can share `app-localizer.secrets.toml` beside the config file. Each entry maps an environment variable name to its value; one file can hold keys for every provider a team uses:
+
+```toml
+OPENAI_API_KEY = "sk-..."
+OPENROUTER_API_KEY = "sk-or-..."
+```
+
+Add the secrets file to the consuming repository's `.gitignore` and distribute it out of band. See [docs/ios-integration.md](docs/ios-integration.md#security-posture) for the full key-handling policy.
+
+### Provider Examples
+
+Any OpenAI-compatible chat completions endpoint works. The default targets OpenAI and reads `OPENAI_API_KEY`.
+
+OpenRouter:
+
+```toml
+base_url = "https://openrouter.ai/api/v1"
+api_key_env = "OPENROUTER_API_KEY"
+model = "anthropic/claude-sonnet-4-6"
+```
+
+Ollama:
+
+```toml
+base_url = "http://localhost:11434/v1"
+api_key_env = ""
+model = "llama3.3"
+```
+
+LM Studio:
+
+```toml
+base_url = "http://localhost:1234/v1"
+api_key_env = ""
+model = "qwen2.5-32b-instruct"
+```
+
+Apple Foundation Models has no direct HTTP API. Point `base_url` at a local OpenAI-compatible bridge and set `api_key_env = ""` if the bridge is keyless.
+
+Leave `reasoning_effort` unset unless the selected model and endpoint accept it. When an endpoint reports the field as unknown or unsupported, the run warns once, retries without it, and omits it for the rest of that run.
+
+## Outputs
+
+### String Catalog Behavior
+
+For each configured catalog and target language, a run:
+
+- Adds missing target-language localizations from the source language.
+- Skips entries marked with `shouldTranslate: false`.
+- Translates `stringUnit` values, nested variation trees, and substitution variations (`%#@name@` / `%arg`).
+- Adds the plural categories the target language's CLDR rules require, even when the source language omits them.
+- Preserves substitution metadata such as `argNum` and `formatSpecifier`, and keeps it in sync with the source language.
+- Preserves localizations for languages outside the current run.
+- Copies whitespace-only values verbatim instead of sending them to the provider.
+
+Catalog writes are atomic. The writer keeps file permissions, syncs contents to disk, sorts JSON keys, and uses Xcode-style spacing before replacing the original file. Catalogs with duplicate JSON keys or unsupported catalog versions are rejected.
+
+### Fastlane Metadata Behavior
+
+Files in the source locale directory are handled by name:
+
+| File | Handling | Limit |
+| --- | --- | --- |
+| `name.txt` | translated | 30 |
+| `subtitle.txt` | translated | 30 |
+| `description.txt` | translated | 4000 |
+| `keywords.txt` | translated, kept comma-separated | 100 |
+| `promotional_text.txt` | translated | 170 |
+| `release_notes.txt` | translated | 4000 |
+| `apple_tv_privacy_policy.txt` | translated | - |
+| `marketing_url.txt`, `support_url.txt`, `privacy_url.txt` | copied verbatim, never sent to the provider | - |
+| `review_information/` | ignored | - |
+
+Non-localized metadata at the root of `metadata_path` (`copyright.txt`, category files, and `review_information/`) lives outside the locale directories and is never touched.
+
+Unrecognized files are skipped with a warning. For prose metadata files, a translation over the App Store character limit is rejected like a placeholder mismatch. If no candidate fits, the file errors and the run fails.
+
+Generated `keywords.txt` translations differ when `keywords_trim_to_fit = true`: spaces around keywords are stripped, case-insensitive duplicates are removed, and trailing keywords are dropped until the comma-joined list fits 100 characters. Dropped terms are logged in a warning. Set `keywords_trim_to_fit = false` to reject over-limit keyword translations instead. `--check` still fails when a source file exceeds its own limit.
+
+Metadata `.txt` files have no per-value translation state, so skip decisions come from the lockfile's per-file source hashes. `--check` validates locked target files against App Store character limits. Other hand-edited target changes with an unchanged source are not detected as pending. Use `--force` to rewrite everything.
+
+### Lockfiles and Skip Behavior
+
+`.app-localizer.lock` is the skip cache. The String Catalog domain writes one beside each catalog. The Fastlane domain writes one at the metadata root.
+
+Commit lockfiles. Without them, later runs have less information and translate more than they need to.
+
+String Catalog lockfile section:
+
+```json
+{
+  "catalogs" : {
+    "Localizable.xcstrings" : {
+      "de" : {
+        "baseUrl" : "https://api.openai.com/v1",
+        "config" : "sha256...",
+        "hash" : "sha256...",
+        "model" : "gpt-5.2",
+        "timestamp" : "2026-06-11T00:00:00+00:00"
+      }
+    }
+  },
+  "generatedBy" : "app-localizer",
+  "version" : 1
+}
+```
+
+Fastlane lockfile section:
+
+```json
+{
+  "fastlane" : {
+    "de-DE" : {
+      "marketing_url.txt" : { "config" : "verbatim", "hash" : "sha256...", "..." : "..." },
+      "name.txt" : {
+        "baseUrl" : "https://api.openai.com/v1",
+        "config" : "sha256...",
+        "hash" : "sha256...",
+        "model" : "gpt-5.2",
+        "timestamp" : "2026-06-11T00:00:00+00:00"
+      }
+    }
+  },
+  "generatedBy" : "app-localizer",
+  "version" : 1
+}
+```
+
+For catalogs, `hash` fingerprints the source-language content per catalog. A language is skipped only when the hashes match and no units are pending.
+
+For metadata, `hash` fingerprints each source file. Skips are per file: a file is translated again when the target is missing, the source changed, or the configuration changed.
+
+`config` fingerprints the endpoint, model, reasoning effort, temperature, candidate count, prompts, and domain-specific validation policy. For metadata, it also includes the character limit and keyword trim policy. `baseUrl` and `model` are informational fields that record what produced an entry.
+
+Unreadable, unsupported, or foreign lockfiles are discarded with a warning and rebuilt on the next run. Sections a domain does not own are preserved.
+
+### Limits and Review
+
+Translations are validated before writing:
+
+- Catalog translations must preserve printf placeholders, Swift interpolation placeholders, and String Catalog substitution tokens.
+- Fastlane metadata translations must fit App Store character limits.
+- Config files must not contain unknown keys, duplicate sources or languages, malformed language tags, or invalid App Store locale codes.
+
+Current limits:
+
+- The catalog lockfile is catalog-level per language, not per key. Per-unit state lives in the catalog itself.
+- Plural variations are expanded to the categories the target language's CLDR rules require (Russian `few` and `many`, for example), translated from the source's `other` form. Languages outside the built-in CLDR table fall back to mirroring the source's categories.
+- Output is a draft. Require human review for high-risk UI, marketing copy, legal text, purchase flows, and short ambiguous strings.
+
+## Team Workflow
+
+### CI
+
+Copy [examples/github-actions/app-localizer.yml](examples/github-actions/app-localizer.yml) into the app repository. Pull requests run `--check` with no API key. Manual workflow dispatch runs translation from a repository secret and opens a draft PR with the generated changes.
+
+If the app repository needs credentials to install App Localizer, update the workflow install step to use the repository's git credential or package source.
+
+For release branches, set `fail_on_untranslated = true` or pass `--fail-on-untranslated` so checks fail while configured targets still have untranslated content.
+
+### App-Team Workflow
+
+See [docs/ios-integration.md](docs/ios-integration.md) for the recommended app-team workflow: API key handling, developer checks, CI translation PRs, review policy, and release-branch behavior.
+
+Run translation before `fastlane deliver` so uploaded metadata is current.
+
+## Development
+
+### Local Development
+
+Install the package editable and run the test suite from the repository root:
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python3 -m pip install -e .
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+CI runs the same suite on every push and pull request against the oldest and newest supported Python versions.
+
+### Releasing
+
+Releases are plain git tags; there is no package registry.
+
+1. Update `version` in `pyproject.toml` and commit to `main`.
+2. Tag the same version with a leading `v`.
+3. Push `main` and the tag.
+
+```sh
+git tag vX.Y.Z
+git push origin main vX.Y.Z
+```
+
+Pushing the tag runs the release workflow. It verifies the tag matches the package version, runs the test suite, builds the sdist and wheel, publishes to PyPI via trusted publishing, and publishes a GitHub Release with generated notes and the build files attached.
+
+Consumers install a pinned release from PyPI:
+
+```sh
+python3 -m pip install "app-localizer==X.Y.Z"
+```
+
+### Compatibility
+
+Versioning follows semantic versioning as of 1.0.0. The stable surface is the CLI flag set, the `app-localizer.toml` config schema, and the `.app-localizer.lock` format. A major release is required to break any of them.
+
+The default model (`gpt-5.2`) is not part of the stable surface and may change in a minor release; pin `model` in the config to control it. Translation output is model-defined and never guaranteed to be stable. The lockfile is a disposable cache: an unreadable or future-version lockfile is discarded and rebuilt, so its format can advance without a breaking change.
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## Contributions
+
+App Localizer is not accepting source contributions at this time. Bug reports will be considered.
+
+## Author
+
+[Kyle Hughes](https://kylehugh.es)
+
+[![Bluesky][bluesky_image]][bluesky_url]  
+[![LinkedIn][linkedin_image]][linkedin_url]  
+[![Mastodon][mastodon_image]][mastodon_url]
+
+[bluesky_image]: https://img.shields.io/badge/Bluesky-0285FF?logo=bluesky&logoColor=fff
+[bluesky_url]: https://bsky.app/profile/kylehugh.es
+[linkedin_image]: https://img.shields.io/badge/LinkedIn-0A66C2?logo=linkedin&logoColor=fff
+[linkedin_url]: https://www.linkedin.com/in/kyle-hughes
+[mastodon_image]: https://img.shields.io/mastodon/follow/109356914477272810?domain=https%3A%2F%2Fmister.computer&style=social
+[mastodon_url]: https://mister.computer/@kyle
+
+## License
+
+App Localizer is available under the MIT license.
+
+See `LICENSE` for details.