android-localisation 1.0.4__tar.gz → 1.0.5__tar.gz

{android_localisation-1.0.4/android_localisation.egg-info → android_localisation-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: android-localisation
-Version: 1.0.4
+Version: 1.0.5
 Summary: Zero-dependency Android strings.xml translation and verification using LLMs (Gemini, OpenAI, Anthropic, Ollama).
 License: MIT
 Project-URL: Homepage, https://github.com/BharathKmalviya/android-llm-localization
@@ -26,13 +26,15 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
 
-# android-llm-localization
+# android-localisation
 
 [![PyPI version](https://img.shields.io/pypi/v/android-localisation.svg)](https://pypi.org/project/android-localisation/)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://pypi.org/project/android-localisation/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Translate your Android `strings.xml` into multiple languages using AI — Gemini, OpenAI, Anthropic, or a local model via Ollama. No paid service, no CSV exports, no copy-paste.
+**PyPI:** [`android-localisation`](https://pypi.org/project/android-localisation/) · **CLI:** `android-localise` · **Repo:** [android-llm-localization](https://github.com/BharathKmalviya/android-llm-localization)
+
+Translate your Android `strings.xml` into multiple languages using AI — Gemini, OpenAI, Anthropic, or a local model via Ollama. No paid translation service, no CSV exports, no copy-paste.
 
 ---
 
@@ -86,7 +88,7 @@ When you run `android-localise translate --api-key YOUR_KEY`, here's exactly wha
 | What | Default |
 |---|---|
 | Provider | Gemini |
-| Model | `gemini-2.5-flash` |
+| Model | `gemini-3.5-flash` |
 | Source directory | `app/src/main/res` |
 | Delay between requests | 5 seconds |
 | App context | none (generic prompt) |
@@ -150,6 +152,7 @@ android-localise translate \
 | `--res-dir` | Path to your `res/` folder | `app/src/main/res` |
 | `--base-url` | API endpoint for local/custom providers | — |
 | `--sleep` | Seconds to wait between language requests | `5.0` |
+| `--timeout` | Seconds to wait for each API response (retries up to 3 times on timeout) | `180` |
 
 ---
 
@@ -157,10 +160,13 @@ android-localise translate \
 
 ```bash
 android-localise fix
+android-localise fix --res-dir path/to/res
 ```
 
 LLMs occasionally produce output that looks correct but breaks the Android build — curly apostrophes (`'`) instead of escaped ones (`\'`), unescaped double quotes, or mangled `%` signs. This command scans every translated `strings.xml` and corrects these silently.
 
+Strings marked `formatted="false"` are skipped — their `%` signs are literal, not format specifiers.
+
 Always run this before `verify` and before building.
 
 ---
@@ -169,11 +175,12 @@ Always run this before `verify` and before building.
 
 ```bash
 android-localise verify
+android-localise verify --res-dir path/to/res
 ```
 
 Takes every translated string that contains a format specifier (`%1$s`, `%d`, `%1$f`, etc.) and calls `String.format()` on it using Java's actual runtime. If a translated string would throw `UnknownFormatConversionException` or `MissingFormatArgumentException` in your app, this catches it before your users do.
 
-Requires `javac` in your PATH. If you don't have it system-wide, run this from the Terminal tab inside Android Studio — it ships with a JDK.
+Strings marked `formatted="false"` are skipped. Requires `javac` in your PATH. If you don't have it system-wide, run this from the Terminal tab inside Android Studio — it ships with a JDK.
 
 ---
 
@@ -190,21 +197,21 @@ Lists every available model and fallback for each provider.
 
 ## Providers
 
-By default the tool uses Gemini with `gemini-2.5-flash`. You can switch providers with `--provider` and optionally pin a specific model with `--model`.
+By default the tool uses Gemini with `gemini-3.5-flash`. You can switch providers with `--provider` and optionally pin a specific model with `--model`.
 
 | Provider | Default model | Fallbacks | API key env var |
 |---|---|---|---|
-| `gemini` _(default)_ | `gemini-2.5-flash` | `gemini-2.0-flash` → `gemini-1.5-flash` → `gemini-1.5-pro` | `GEMINI_API_KEY` |
-| `openai` | `gpt-4o-mini` | `gpt-4o` → `gpt-3.5-turbo` | `OPENAI_API_KEY` |
-| `anthropic` | `claude-3-5-haiku-latest` | `claude-3-5-sonnet-latest` → `claude-3-opus-latest` | `ANTHROPIC_API_KEY` |
-| `custom` | set with `--model` | none | — |
+| `gemini` _(default)_ | `gemini-3.5-flash` | `gemini-3.1-flash-lite` → `gemini-2.5-flash` → `gemini-2.5-flash-lite` | `GEMINI_API_KEY` |
+| `openai` | `gpt-5.4-mini` | `gpt-5-mini` → `gpt-4o-mini` | `OPENAI_API_KEY` |
+| `anthropic` | `claude-haiku-4-5` | `claude-sonnet-4-6` → `claude-opus-4-8` | `ANTHROPIC_API_KEY` |
+| `custom` | set with `--model` | none | `OPENAI_API_KEY` (optional) |
 
 If the default model returns a "model not found" error (e.g. it was deprecated), the tool automatically retries with the next fallback. If you pin a model with `--model`, no fallback is used.
 
 **Using OpenAI:**
 ```bash
 android-localise translate --provider openai --api-key YOUR_KEY
-android-localise translate --provider openai --model gpt-4o --api-key YOUR_KEY
+android-localise translate --provider openai --model gpt-5.4-mini --api-key YOUR_KEY
 ```
 
 **Using Anthropic:**
@@ -239,6 +246,9 @@ export GEMINI_API_KEY=your_key
 
 # Windows PowerShell
 $env:GEMINI_API_KEY = "your_key"
+
+# Windows CMD
+set GEMINI_API_KEY=your_key
 ```
 
 Then just run:
@@ -251,19 +261,25 @@ android-localise translate
 | `GEMINI_API_KEY` | `--provider gemini` |
 | `OPENAI_API_KEY` | `--provider openai` and `--provider custom` |
 | `ANTHROPIC_API_KEY` | `--provider anthropic` |
+| `API_KEY` | fallback for any provider if the provider-specific var is not set |
 
 ---
 
 ## Full workflow example
 
 ```bash
-# First time setup — create locale folders
+# First time setup — create locale folders (macOS / Linux)
 mkdir -p app/src/main/res/values-hi
 mkdir -p app/src/main/res/values-es
 mkdir -p app/src/main/res/values-de
 
+# Windows PowerShell
+New-Item -ItemType Directory -Force app/src/main/res/values-hi
+New-Item -ItemType Directory -Force app/src/main/res/values-es
+New-Item -ItemType Directory -Force app/src/main/res/values-de
+
 # Set your key once
-export GEMINI_API_KEY=your_key
+export GEMINI_API_KEY=your_key   # or $env:GEMINI_API_KEY on Windows
 
 # Translate, fix, verify
 android-localise translate --app-context "a habit tracking app"
@@ -278,23 +294,83 @@ After this, whenever you add or change strings in your English `strings.xml`, ru
 
 ---
 
+## Platform support
+
+This project is developed and **manually tested on Windows only** at the moment. It is written in pure Python (stdlib only) and should run on macOS and Linux, but those platforms have **not been verified** by the maintainer yet.
+
+We especially need help testing on:
+
+- **macOS** — `translate`, `fix`, `verify` (including `javac` / Android Studio terminal)
+- **Linux** — same workflow, plus common CI environments
+
+If you use another OS, please try the [quick start](#quick-start) workflow and report what you find:
+
+- **Works?** — open a [GitHub issue](https://github.com/BharathKmalviya/android-llm-localization/issues) titled e.g. `Confirmed working on macOS 14` with your OS, Python version, and provider used
+- **Broken?** — open a [bug report](https://github.com/BharathKmalviya/android-llm-localization/issues/new?template=bug_report.md) with the full error output
+- **Want to help more?** — see [Contributing](#contributing) and [CONTRIBUTING.md](CONTRIBUTING.md)
+
+Cross-platform fixes and test notes in pull requests are very welcome.
+
+---
+
+## Limitations
+
+| Topic | Detail |
+|---|---|
+| **Platform testing** | Maintainer-tested on **Windows only** — macOS and Linux need community verification (see [Platform support](#platform-support)) |
+| **Scope** | Translates `values/strings.xml` only — not `plurals.xml`, `arrays.xml`, or other resource files |
+| **Overwrite** | Each run replaces the entire `strings.xml` in each locale folder with a fresh LLM translation |
+| **Folder scan** | Without `--languages`, every `values-*` folder is treated as a locale. Qualifier-only folders like `values-night` or `values-sw600dp` may be picked up incorrectly — prefer `--languages` or keep only locale folders in `res/` |
+| **Network** | `translate` requires internet access to reach the LLM API (except local `custom` providers) |
+| **JDK** | `verify` requires `javac` on your PATH |
+
+---
+
+## Troubleshooting
+
+| Problem | What to try |
+|---|---|
+| `Could not find English strings.xml` | Check `--res-dir` points to your `res/` folder and `values/strings.xml` exists |
+| `No locale directories found` | Add `--languages hi,es,fr` or create `values-<lang>/` folders manually |
+| API auth errors | Confirm your key env var or `--api-key` matches the `--provider` |
+| `javac` not found | Install a JDK or run `verify` from Android Studio's terminal |
+| Build fails on apostrophes | Run `android-localise fix` before building |
+| `%` crashes at runtime | Run `android-localise verify` — it catches bad format specifiers before release |
+| Wrong folder translated | Use `--languages` to target exact locale codes instead of folder scan |
+
+---
+
 ## Roadmap
 
 - [ ] **iOS support** — translate `Localizable.strings` and `Localizable.xcstrings` for iOS/macOS apps. The LLM prompt and provider logic is already in place — it mainly needs a parser for Apple's strings format and the right folder structure (`<lang>.lproj/`). Good first contribution if you're familiar with iOS projects.
+- [ ] **Smarter locale folder detection** — skip non-locale `values-*` qualifiers (`night`, `sw600dp`, `v21`, etc.) when scanning without `--languages`
+- [ ] **Automated test suite** — unit tests for `fix`, XML parsing, and format-specifier edge cases
+- [ ] **Cross-platform verification** — confirm `translate`, `fix`, and `verify` on macOS and Linux (Windows is maintainer-tested today)
 
 ---
 
 ## Contributing
 
-Bug reports and pull requests are welcome. For larger changes, open an issue first.
+Bug reports, pull requests, and **cross-platform testing** are all welcome. For larger changes, open an issue first.
+
+**No code required** — if you are on macOS or Linux, running the tool and filing an issue (pass or fail) is a real contribution. See [Platform support](#platform-support).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, branch strategy, and release process.
 
 ```bash
 git clone https://github.com/BharathKmalviya/android-llm-localization
 cd android-llm-localization
+git checkout dev
 pip install -e .
 ```
 
-Releases are automated via GitHub Actions — bump the version in `pyproject.toml` and `__init__.py`, update `CHANGELOG.md`, and push to `master`.
+Day-to-day work happens on the `dev` branch. Releases are merged to `master` via pull request, which triggers automated PyPI publishing.
+
+---
+
+## Security
+
+To report a security vulnerability, see [SECURITY.md](SECURITY.md). Please do not open public issues for security-sensitive reports.
 
 ---
 

{android_localisation-1.0.4 → android_localisation-1.0.5}/README.md

@@ -1,10 +1,12 @@
-# android-llm-localization
+# android-localisation
 
 [![PyPI version](https://img.shields.io/pypi/v/android-localisation.svg)](https://pypi.org/project/android-localisation/)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://pypi.org/project/android-localisation/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Translate your Android `strings.xml` into multiple languages using AI — Gemini, OpenAI, Anthropic, or a local model via Ollama. No paid service, no CSV exports, no copy-paste.
+**PyPI:** [`android-localisation`](https://pypi.org/project/android-localisation/) · **CLI:** `android-localise` · **Repo:** [android-llm-localization](https://github.com/BharathKmalviya/android-llm-localization)
+
+Translate your Android `strings.xml` into multiple languages using AI — Gemini, OpenAI, Anthropic, or a local model via Ollama. No paid translation service, no CSV exports, no copy-paste.
 
 ---
 
@@ -58,7 +60,7 @@ When you run `android-localise translate --api-key YOUR_KEY`, here's exactly wha
 | What | Default |
 |---|---|
 | Provider | Gemini |
-| Model | `gemini-2.5-flash` |
+| Model | `gemini-3.5-flash` |
 | Source directory | `app/src/main/res` |
 | Delay between requests | 5 seconds |
 | App context | none (generic prompt) |
@@ -122,6 +124,7 @@ android-localise translate \
 | `--res-dir` | Path to your `res/` folder | `app/src/main/res` |
 | `--base-url` | API endpoint for local/custom providers | — |
 | `--sleep` | Seconds to wait between language requests | `5.0` |
+| `--timeout` | Seconds to wait for each API response (retries up to 3 times on timeout) | `180` |
 
 ---
 
@@ -129,10 +132,13 @@ android-localise translate \
 
 ```bash
 android-localise fix
+android-localise fix --res-dir path/to/res
 ```
 
 LLMs occasionally produce output that looks correct but breaks the Android build — curly apostrophes (`'`) instead of escaped ones (`\'`), unescaped double quotes, or mangled `%` signs. This command scans every translated `strings.xml` and corrects these silently.
 
+Strings marked `formatted="false"` are skipped — their `%` signs are literal, not format specifiers.
+
 Always run this before `verify` and before building.
 
 ---
@@ -141,11 +147,12 @@ Always run this before `verify` and before building.
 
 ```bash
 android-localise verify
+android-localise verify --res-dir path/to/res
 ```
 
 Takes every translated string that contains a format specifier (`%1$s`, `%d`, `%1$f`, etc.) and calls `String.format()` on it using Java's actual runtime. If a translated string would throw `UnknownFormatConversionException` or `MissingFormatArgumentException` in your app, this catches it before your users do.
 
-Requires `javac` in your PATH. If you don't have it system-wide, run this from the Terminal tab inside Android Studio — it ships with a JDK.
+Strings marked `formatted="false"` are skipped. Requires `javac` in your PATH. If you don't have it system-wide, run this from the Terminal tab inside Android Studio — it ships with a JDK.
 
 ---
 
@@ -162,21 +169,21 @@ Lists every available model and fallback for each provider.
 
 ## Providers
 
-By default the tool uses Gemini with `gemini-2.5-flash`. You can switch providers with `--provider` and optionally pin a specific model with `--model`.
+By default the tool uses Gemini with `gemini-3.5-flash`. You can switch providers with `--provider` and optionally pin a specific model with `--model`.
 
 | Provider | Default model | Fallbacks | API key env var |
 |---|---|---|---|
-| `gemini` _(default)_ | `gemini-2.5-flash` | `gemini-2.0-flash` → `gemini-1.5-flash` → `gemini-1.5-pro` | `GEMINI_API_KEY` |
-| `openai` | `gpt-4o-mini` | `gpt-4o` → `gpt-3.5-turbo` | `OPENAI_API_KEY` |
-| `anthropic` | `claude-3-5-haiku-latest` | `claude-3-5-sonnet-latest` → `claude-3-opus-latest` | `ANTHROPIC_API_KEY` |
-| `custom` | set with `--model` | none | — |
+| `gemini` _(default)_ | `gemini-3.5-flash` | `gemini-3.1-flash-lite` → `gemini-2.5-flash` → `gemini-2.5-flash-lite` | `GEMINI_API_KEY` |
+| `openai` | `gpt-5.4-mini` | `gpt-5-mini` → `gpt-4o-mini` | `OPENAI_API_KEY` |
+| `anthropic` | `claude-haiku-4-5` | `claude-sonnet-4-6` → `claude-opus-4-8` | `ANTHROPIC_API_KEY` |
+| `custom` | set with `--model` | none | `OPENAI_API_KEY` (optional) |
 
 If the default model returns a "model not found" error (e.g. it was deprecated), the tool automatically retries with the next fallback. If you pin a model with `--model`, no fallback is used.
 
 **Using OpenAI:**
 ```bash
 android-localise translate --provider openai --api-key YOUR_KEY
-android-localise translate --provider openai --model gpt-4o --api-key YOUR_KEY
+android-localise translate --provider openai --model gpt-5.4-mini --api-key YOUR_KEY
 ```
 
 **Using Anthropic:**
@@ -211,6 +218,9 @@ export GEMINI_API_KEY=your_key
 
 # Windows PowerShell
 $env:GEMINI_API_KEY = "your_key"
+
+# Windows CMD
+set GEMINI_API_KEY=your_key
 ```
 
 Then just run:
@@ -223,19 +233,25 @@ android-localise translate
 | `GEMINI_API_KEY` | `--provider gemini` |
 | `OPENAI_API_KEY` | `--provider openai` and `--provider custom` |
 | `ANTHROPIC_API_KEY` | `--provider anthropic` |
+| `API_KEY` | fallback for any provider if the provider-specific var is not set |
 
 ---
 
 ## Full workflow example
 
 ```bash
-# First time setup — create locale folders
+# First time setup — create locale folders (macOS / Linux)
 mkdir -p app/src/main/res/values-hi
 mkdir -p app/src/main/res/values-es
 mkdir -p app/src/main/res/values-de
 
+# Windows PowerShell
+New-Item -ItemType Directory -Force app/src/main/res/values-hi
+New-Item -ItemType Directory -Force app/src/main/res/values-es
+New-Item -ItemType Directory -Force app/src/main/res/values-de
+
 # Set your key once
-export GEMINI_API_KEY=your_key
+export GEMINI_API_KEY=your_key   # or $env:GEMINI_API_KEY on Windows
 
 # Translate, fix, verify
 android-localise translate --app-context "a habit tracking app"
@@ -250,23 +266,83 @@ After this, whenever you add or change strings in your English `strings.xml`, ru
 
 ---
 
+## Platform support
+
+This project is developed and **manually tested on Windows only** at the moment. It is written in pure Python (stdlib only) and should run on macOS and Linux, but those platforms have **not been verified** by the maintainer yet.
+
+We especially need help testing on:
+
+- **macOS** — `translate`, `fix`, `verify` (including `javac` / Android Studio terminal)
+- **Linux** — same workflow, plus common CI environments
+
+If you use another OS, please try the [quick start](#quick-start) workflow and report what you find:
+
+- **Works?** — open a [GitHub issue](https://github.com/BharathKmalviya/android-llm-localization/issues) titled e.g. `Confirmed working on macOS 14` with your OS, Python version, and provider used
+- **Broken?** — open a [bug report](https://github.com/BharathKmalviya/android-llm-localization/issues/new?template=bug_report.md) with the full error output
+- **Want to help more?** — see [Contributing](#contributing) and [CONTRIBUTING.md](CONTRIBUTING.md)
+
+Cross-platform fixes and test notes in pull requests are very welcome.
+
+---
+
+## Limitations
+
+| Topic | Detail |
+|---|---|
+| **Platform testing** | Maintainer-tested on **Windows only** — macOS and Linux need community verification (see [Platform support](#platform-support)) |
+| **Scope** | Translates `values/strings.xml` only — not `plurals.xml`, `arrays.xml`, or other resource files |
+| **Overwrite** | Each run replaces the entire `strings.xml` in each locale folder with a fresh LLM translation |
+| **Folder scan** | Without `--languages`, every `values-*` folder is treated as a locale. Qualifier-only folders like `values-night` or `values-sw600dp` may be picked up incorrectly — prefer `--languages` or keep only locale folders in `res/` |
+| **Network** | `translate` requires internet access to reach the LLM API (except local `custom` providers) |
+| **JDK** | `verify` requires `javac` on your PATH |
+
+---
+
+## Troubleshooting
+
+| Problem | What to try |
+|---|---|
+| `Could not find English strings.xml` | Check `--res-dir` points to your `res/` folder and `values/strings.xml` exists |
+| `No locale directories found` | Add `--languages hi,es,fr` or create `values-<lang>/` folders manually |
+| API auth errors | Confirm your key env var or `--api-key` matches the `--provider` |
+| `javac` not found | Install a JDK or run `verify` from Android Studio's terminal |
+| Build fails on apostrophes | Run `android-localise fix` before building |
+| `%` crashes at runtime | Run `android-localise verify` — it catches bad format specifiers before release |
+| Wrong folder translated | Use `--languages` to target exact locale codes instead of folder scan |
+
+---
+
 ## Roadmap
 
 - [ ] **iOS support** — translate `Localizable.strings` and `Localizable.xcstrings` for iOS/macOS apps. The LLM prompt and provider logic is already in place — it mainly needs a parser for Apple's strings format and the right folder structure (`<lang>.lproj/`). Good first contribution if you're familiar with iOS projects.
+- [ ] **Smarter locale folder detection** — skip non-locale `values-*` qualifiers (`night`, `sw600dp`, `v21`, etc.) when scanning without `--languages`
+- [ ] **Automated test suite** — unit tests for `fix`, XML parsing, and format-specifier edge cases
+- [ ] **Cross-platform verification** — confirm `translate`, `fix`, and `verify` on macOS and Linux (Windows is maintainer-tested today)
 
 ---
 
 ## Contributing
 
-Bug reports and pull requests are welcome. For larger changes, open an issue first.
+Bug reports, pull requests, and **cross-platform testing** are all welcome. For larger changes, open an issue first.
+
+**No code required** — if you are on macOS or Linux, running the tool and filing an issue (pass or fail) is a real contribution. See [Platform support](#platform-support).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, branch strategy, and release process.
 
 ```bash
 git clone https://github.com/BharathKmalviya/android-llm-localization
 cd android-llm-localization
+git checkout dev
 pip install -e .
 ```
 
-Releases are automated via GitHub Actions — bump the version in `pyproject.toml` and `__init__.py`, update `CHANGELOG.md`, and push to `master`.
+Day-to-day work happens on the `dev` branch. Releases are merged to `master` via pull request, which triggers automated PyPI publishing.
+
+---
+
+## Security
+
+To report a security vulnerability, see [SECURITY.md](SECURITY.md). Please do not open public issues for security-sensitive reports.
 
 ---
 

{android_localisation-1.0.4 → android_localisation-1.0.5}/android_localisation/__init__.py

@@ -2,4 +2,4 @@
 android-localisation: Zero-dependency Android strings.xml translation using LLMs.
 """
 
-__version__ = "1.0.4"
+__version__ = "1.0.5"

{android_localisation-1.0.4 → android_localisation-1.0.5}/android_localisation/cli.py

@@ -31,6 +31,11 @@ def main():
     translate_parser.add_argument("--base-url", help="Custom OpenAI-compatible endpoint URL (required for 'custom' provider)")
     translate_parser.add_argument("--app-context", help="Short description of your app for better translations")
     translate_parser.add_argument("--sleep", type=float, default=5.0, help="Seconds between API requests (default: 5.0)")
+    from android_localisation.translate import DEFAULT_API_TIMEOUT
+    translate_parser.add_argument(
+        "--timeout", type=float, default=DEFAULT_API_TIMEOUT,
+        help=f"Seconds to wait for each API response (default: {DEFAULT_API_TIMEOUT})",
+    )
     translate_parser.add_argument("--languages", help="Comma-separated language codes, e.g. hi,es,fr,de — creates folders and strings.xml automatically")
 
     # --- fix ---
@@ -75,7 +80,7 @@ def main():
         print("    → Any model name your local server supports (must use --model)")
         print()
         print("  Tip: use --model to pick any model, e.g:")
-        print("    android-localise translate --provider openai --model gpt-4o --api-key KEY")
+        print("    android-localise translate --provider openai --model gpt-5.4-mini --api-key KEY")
         print()
 
 

{android_localisation-1.0.4 → android_localisation-1.0.5}/android_localisation/translate.py

@@ -1,32 +1,34 @@
 import os
 import re
 import time
+import socket
 import argparse
 import urllib.request
 import urllib.error
 import json
 
 DEFAULT_RES_DIR = "app/src/main/res"
-API_TIMEOUT = 60  # seconds
+DEFAULT_API_TIMEOUT = 180  # seconds (3 minutes) — large strings.xml files can exceed 60s
+MAX_TIMEOUT_RETRIES = 2
 
 # Ordered list of models per provider.
 # First entry = default. Rest = automatic fallbacks (used only when user hasn't pinned a model).
 PROVIDER_MODELS = {
     "gemini": [
+        "gemini-3.5-flash",
+        "gemini-3.1-flash-lite",
         "gemini-2.5-flash",
-        "gemini-2.0-flash",
-        "gemini-1.5-flash",
-        "gemini-1.5-pro",
+        "gemini-2.5-flash-lite",
     ],
     "openai": [
+        "gpt-5.4-mini",
+        "gpt-5-mini",
         "gpt-4o-mini",
-        "gpt-4o",
-        "gpt-3.5-turbo",
     ],
     "anthropic": [
-        "claude-3-5-haiku-latest",
-        "claude-3-5-sonnet-latest",
-        "claude-3-opus-latest",
+        "claude-haiku-4-5",
+        "claude-sonnet-4-6",
+        "claude-opus-4-8",
     ],
     "custom": [],  # user must specify --model
 }
@@ -133,27 +135,52 @@ def _is_model_not_found(http_code, body):
     ])
 
 
-def call_gemini(api_key, model, prompt):
+def _urlopen_with_retries(req, provider_label, timeout):
+    """
+    Execute an HTTP request with timeout/network error handling and retries on timeout.
+    Returns (response_bytes, model_not_found).
+    """
+    for attempt in range(MAX_TIMEOUT_RETRIES + 1):
+        if attempt > 0:
+            wait = attempt * 3
+            print(f"  🔁 {provider_label} timed out — retrying ({attempt}/{MAX_TIMEOUT_RETRIES}) in {wait}s...")
+            time.sleep(wait)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as response:
+                return response.read(), False
+        except urllib.error.HTTPError as e:
+            body = _read_error_body(e)
+            model_gone = _is_model_not_found(e.code, body)
+            print(f"  ❌ {provider_label} API Error: {e.code} - {body}")
+            return None, model_gone
+        except (TimeoutError, socket.timeout):
+            if attempt < MAX_TIMEOUT_RETRIES:
+                continue
+            print(f"  ❌ {provider_label} API timed out after {timeout}s ({MAX_TIMEOUT_RETRIES + 1} attempts)")
+            return None, False
+        except urllib.error.URLError as e:
+            print(f"  ❌ {provider_label} network error: {e.reason}")
+            return None, False
+    return None, False
+
+
+def call_gemini(api_key, model, prompt, timeout=DEFAULT_API_TIMEOUT):
     url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={api_key}"
     headers = {"Content-Type": "application/json"}
     data = {"contents": [{"parts": [{"text": prompt}]}]}
     req = urllib.request.Request(url, data=json.dumps(data).encode("utf-8"), headers=headers, method="POST")
-    try:
-        with urllib.request.urlopen(req, timeout=API_TIMEOUT) as response:
-            result = json.loads(response.read().decode("utf-8"))
-            candidates = result.get("candidates", [])
-            if not candidates:
-                print("  ❌ Gemini returned no candidates.")
-                return None, False
-            return result["candidates"][0].get("content", {}).get("parts", [{}])[0].get("text", ""), False
-    except urllib.error.HTTPError as e:
-        body = _read_error_body(e)
-        model_gone = _is_model_not_found(e.code, body)
-        print(f"  ❌ Gemini API Error: {e.code} - {body}")
+    raw, model_gone = _urlopen_with_retries(req, "Gemini", timeout)
+    if raw is None:
         return None, model_gone
+    result = json.loads(raw.decode("utf-8"))
+    candidates = result.get("candidates", [])
+    if not candidates:
+        print("  ❌ Gemini returned no candidates.")
+        return None, False
+    return result["candidates"][0].get("content", {}).get("parts", [{}])[0].get("text", ""), False
 
 
-def call_openai_compatible(api_key, base_url, model, prompt):
+def call_openai_compatible(api_key, base_url, model, prompt, timeout=DEFAULT_API_TIMEOUT):
     headers = {
         "Content-Type": "application/json",
         "Authorization": f"Bearer {api_key or ''}",
@@ -163,22 +190,18 @@ def call_openai_compatible(api_key, base_url, model, prompt):
         "messages": [{"role": "user", "content": prompt}],
     }
     req = urllib.request.Request(base_url, data=json.dumps(data).encode("utf-8"), headers=headers, method="POST")
-    try:
-        with urllib.request.urlopen(req, timeout=API_TIMEOUT) as response:
-            result = json.loads(response.read().decode("utf-8"))
-            choices = result.get("choices", [])
-            if not choices:
-                print("  ❌ OpenAI returned no choices.")
-                return None, False
-            return choices[0].get("message", {}).get("content", ""), False
-    except urllib.error.HTTPError as e:
-        body = _read_error_body(e)
-        model_gone = _is_model_not_found(e.code, body)
-        print(f"  ❌ OpenAI (compatible) API Error: {e.code} - {body}")
+    raw, model_gone = _urlopen_with_retries(req, "OpenAI (compatible)", timeout)
+    if raw is None:
         return None, model_gone
+    result = json.loads(raw.decode("utf-8"))
+    choices = result.get("choices", [])
+    if not choices:
+        print("  ❌ OpenAI returned no choices.")
+        return None, False
+    return choices[0].get("message", {}).get("content", ""), False
 
 
-def call_anthropic(api_key, model, prompt):
+def call_anthropic(api_key, model, prompt, timeout=DEFAULT_API_TIMEOUT):
     url = "https://api.anthropic.com/v1/messages"
     headers = {
         "Content-Type": "application/json",
@@ -191,37 +214,33 @@ def call_anthropic(api_key, model, prompt):
         "messages": [{"role": "user", "content": prompt}],
     }
     req = urllib.request.Request(url, data=json.dumps(data).encode("utf-8"), headers=headers, method="POST")
-    try:
-        with urllib.request.urlopen(req, timeout=API_TIMEOUT) as response:
-            result = json.loads(response.read().decode("utf-8"))
-            content = result.get("content", [])
-            if not content:
-                print("  ❌ Anthropic returned no content.")
-                return None, False
-            return content[0].get("text", ""), False
-    except urllib.error.HTTPError as e:
-        body = _read_error_body(e)
-        model_gone = _is_model_not_found(e.code, body)
-        print(f"  ❌ Anthropic API Error: {e.code} - {body}")
+    raw, model_gone = _urlopen_with_retries(req, "Anthropic", timeout)
+    if raw is None:
         return None, model_gone
+    result = json.loads(raw.decode("utf-8"))
+    content = result.get("content", [])
+    if not content:
+        print("  ❌ Anthropic returned no content.")
+        return None, False
+    return content[0].get("text", ""), False
 
 
-def _call_provider(provider, api_key, model, prompt, base_url=None):
+def _call_provider(provider, api_key, model, prompt, base_url=None, timeout=DEFAULT_API_TIMEOUT):
     """Dispatches to the right API. Returns (text, model_not_found)."""
     if provider == "gemini":
-        return call_gemini(api_key, model, prompt)
+        return call_gemini(api_key, model, prompt, timeout)
     elif provider == "openai":
         url = base_url if base_url else "https://api.openai.com/v1/chat/completions"
-        return call_openai_compatible(api_key, url, model, prompt)
+        return call_openai_compatible(api_key, url, model, prompt, timeout)
     elif provider == "anthropic":
-        return call_anthropic(api_key, model, prompt)
+        return call_anthropic(api_key, model, prompt, timeout)
     else:
         print(f"❌ Unknown provider: {provider}")
         return None, False
 
 
 def translate_xml(provider, api_key, model, source_xml, target_folder_name, app_context,
-                  base_url=None, fallback_models=None):
+                  base_url=None, fallback_models=None, timeout=DEFAULT_API_TIMEOUT):
     """
     Calls the selected provider API to translate the XML.
     If the model is not found and fallback_models are provided, retries with the next one.
@@ -233,7 +252,9 @@ def translate_xml(provider, api_key, model, source_xml, target_folder_name, app_
     for attempt_model in models_to_try:
         if attempt_model != model:
             print(f"  ↩️  Falling back to model: {attempt_model}")
-        result, model_not_found = _call_provider(provider, api_key, attempt_model, prompt, base_url)
+        result, model_not_found = _call_provider(
+            provider, api_key, attempt_model, prompt, base_url, timeout
+        )
         if result is not None:
             return clean_xml_response(result), attempt_model
         if not model_not_found:
@@ -252,6 +273,8 @@ def _parse_args(args=None):
     parser.add_argument("--base-url")
     parser.add_argument("--app-context")
     parser.add_argument("--sleep", type=float, default=5.0)
+    parser.add_argument("--timeout", type=float, default=DEFAULT_API_TIMEOUT,
+                        help=f"Seconds to wait for each API response (default: {DEFAULT_API_TIMEOUT})")
     parser.add_argument("--languages", help="Comma-separated language codes to translate into, e.g. hi,es,fr,de. Creates folders automatically if they don't exist.")
     return parser.parse_args(args)
 
@@ -333,7 +356,7 @@ def main(args=None):
 
         translated_xml, used_model = translate_xml(
             actual_provider, api_key, model, source_xml,
-            folder, args.app_context, args.base_url, fallback_models
+            folder, args.app_context, args.base_url, fallback_models, args.timeout
         )
 
         if translated_xml and "<resources" in translated_xml and "</resources>" in translated_xml:

{android_localisation-1.0.4 → android_localisation-1.0.5/android_localisation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: android-localisation
-Version: 1.0.4
+Version: 1.0.5
 Summary: Zero-dependency Android strings.xml translation and verification using LLMs (Gemini, OpenAI, Anthropic, Ollama).
 License: MIT
 Project-URL: Homepage, https://github.com/BharathKmalviya/android-llm-localization
@@ -26,13 +26,15 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
 
-# android-llm-localization
+# android-localisation
 
 [![PyPI version](https://img.shields.io/pypi/v/android-localisation.svg)](https://pypi.org/project/android-localisation/)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://pypi.org/project/android-localisation/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Translate your Android `strings.xml` into multiple languages using AI — Gemini, OpenAI, Anthropic, or a local model via Ollama. No paid service, no CSV exports, no copy-paste.
+**PyPI:** [`android-localisation`](https://pypi.org/project/android-localisation/) · **CLI:** `android-localise` · **Repo:** [android-llm-localization](https://github.com/BharathKmalviya/android-llm-localization)
+
+Translate your Android `strings.xml` into multiple languages using AI — Gemini, OpenAI, Anthropic, or a local model via Ollama. No paid translation service, no CSV exports, no copy-paste.
 
 ---
 
@@ -86,7 +88,7 @@ When you run `android-localise translate --api-key YOUR_KEY`, here's exactly wha
 | What | Default |
 |---|---|
 | Provider | Gemini |
-| Model | `gemini-2.5-flash` |
+| Model | `gemini-3.5-flash` |
 | Source directory | `app/src/main/res` |
 | Delay between requests | 5 seconds |
 | App context | none (generic prompt) |
@@ -150,6 +152,7 @@ android-localise translate \
 | `--res-dir` | Path to your `res/` folder | `app/src/main/res` |
 | `--base-url` | API endpoint for local/custom providers | — |
 | `--sleep` | Seconds to wait between language requests | `5.0` |
+| `--timeout` | Seconds to wait for each API response (retries up to 3 times on timeout) | `180` |
 
 ---
 
@@ -157,10 +160,13 @@ android-localise translate \
 
 ```bash
 android-localise fix
+android-localise fix --res-dir path/to/res
 ```
 
 LLMs occasionally produce output that looks correct but breaks the Android build — curly apostrophes (`'`) instead of escaped ones (`\'`), unescaped double quotes, or mangled `%` signs. This command scans every translated `strings.xml` and corrects these silently.
 
+Strings marked `formatted="false"` are skipped — their `%` signs are literal, not format specifiers.
+
 Always run this before `verify` and before building.
 
 ---
@@ -169,11 +175,12 @@ Always run this before `verify` and before building.
 
 ```bash
 android-localise verify
+android-localise verify --res-dir path/to/res
 ```
 
 Takes every translated string that contains a format specifier (`%1$s`, `%d`, `%1$f`, etc.) and calls `String.format()` on it using Java's actual runtime. If a translated string would throw `UnknownFormatConversionException` or `MissingFormatArgumentException` in your app, this catches it before your users do.
 
-Requires `javac` in your PATH. If you don't have it system-wide, run this from the Terminal tab inside Android Studio — it ships with a JDK.
+Strings marked `formatted="false"` are skipped. Requires `javac` in your PATH. If you don't have it system-wide, run this from the Terminal tab inside Android Studio — it ships with a JDK.
 
 ---
 
@@ -190,21 +197,21 @@ Lists every available model and fallback for each provider.
 
 ## Providers
 
-By default the tool uses Gemini with `gemini-2.5-flash`. You can switch providers with `--provider` and optionally pin a specific model with `--model`.
+By default the tool uses Gemini with `gemini-3.5-flash`. You can switch providers with `--provider` and optionally pin a specific model with `--model`.
 
 | Provider | Default model | Fallbacks | API key env var |
 |---|---|---|---|
-| `gemini` _(default)_ | `gemini-2.5-flash` | `gemini-2.0-flash` → `gemini-1.5-flash` → `gemini-1.5-pro` | `GEMINI_API_KEY` |
-| `openai` | `gpt-4o-mini` | `gpt-4o` → `gpt-3.5-turbo` | `OPENAI_API_KEY` |
-| `anthropic` | `claude-3-5-haiku-latest` | `claude-3-5-sonnet-latest` → `claude-3-opus-latest` | `ANTHROPIC_API_KEY` |
-| `custom` | set with `--model` | none | — |
+| `gemini` _(default)_ | `gemini-3.5-flash` | `gemini-3.1-flash-lite` → `gemini-2.5-flash` → `gemini-2.5-flash-lite` | `GEMINI_API_KEY` |
+| `openai` | `gpt-5.4-mini` | `gpt-5-mini` → `gpt-4o-mini` | `OPENAI_API_KEY` |
+| `anthropic` | `claude-haiku-4-5` | `claude-sonnet-4-6` → `claude-opus-4-8` | `ANTHROPIC_API_KEY` |
+| `custom` | set with `--model` | none | `OPENAI_API_KEY` (optional) |
 
 If the default model returns a "model not found" error (e.g. it was deprecated), the tool automatically retries with the next fallback. If you pin a model with `--model`, no fallback is used.
 
 **Using OpenAI:**
 ```bash
 android-localise translate --provider openai --api-key YOUR_KEY
-android-localise translate --provider openai --model gpt-4o --api-key YOUR_KEY
+android-localise translate --provider openai --model gpt-5.4-mini --api-key YOUR_KEY
 ```
 
 **Using Anthropic:**
@@ -239,6 +246,9 @@ export GEMINI_API_KEY=your_key
 
 # Windows PowerShell
 $env:GEMINI_API_KEY = "your_key"
+
+# Windows CMD
+set GEMINI_API_KEY=your_key
 ```
 
 Then just run:
@@ -251,19 +261,25 @@ android-localise translate
 | `GEMINI_API_KEY` | `--provider gemini` |
 | `OPENAI_API_KEY` | `--provider openai` and `--provider custom` |
 | `ANTHROPIC_API_KEY` | `--provider anthropic` |
+| `API_KEY` | fallback for any provider if the provider-specific var is not set |
 
 ---
 
 ## Full workflow example
 
 ```bash
-# First time setup — create locale folders
+# First time setup — create locale folders (macOS / Linux)
 mkdir -p app/src/main/res/values-hi
 mkdir -p app/src/main/res/values-es
 mkdir -p app/src/main/res/values-de
 
+# Windows PowerShell
+New-Item -ItemType Directory -Force app/src/main/res/values-hi
+New-Item -ItemType Directory -Force app/src/main/res/values-es
+New-Item -ItemType Directory -Force app/src/main/res/values-de
+
 # Set your key once
-export GEMINI_API_KEY=your_key
+export GEMINI_API_KEY=your_key   # or $env:GEMINI_API_KEY on Windows
 
 # Translate, fix, verify
 android-localise translate --app-context "a habit tracking app"
@@ -278,23 +294,83 @@ After this, whenever you add or change strings in your English `strings.xml`, ru
 
 ---
 
+## Platform support
+
+This project is developed and **manually tested on Windows only** at the moment. It is written in pure Python (stdlib only) and should run on macOS and Linux, but those platforms have **not been verified** by the maintainer yet.
+
+We especially need help testing on:
+
+- **macOS** — `translate`, `fix`, `verify` (including `javac` / Android Studio terminal)
+- **Linux** — same workflow, plus common CI environments
+
+If you use another OS, please try the [quick start](#quick-start) workflow and report what you find:
+
+- **Works?** — open a [GitHub issue](https://github.com/BharathKmalviya/android-llm-localization/issues) titled e.g. `Confirmed working on macOS 14` with your OS, Python version, and provider used
+- **Broken?** — open a [bug report](https://github.com/BharathKmalviya/android-llm-localization/issues/new?template=bug_report.md) with the full error output
+- **Want to help more?** — see [Contributing](#contributing) and [CONTRIBUTING.md](CONTRIBUTING.md)
+
+Cross-platform fixes and test notes in pull requests are very welcome.
+
+---
+
+## Limitations
+
+| Topic | Detail |
+|---|---|
+| **Platform testing** | Maintainer-tested on **Windows only** — macOS and Linux need community verification (see [Platform support](#platform-support)) |
+| **Scope** | Translates `values/strings.xml` only — not `plurals.xml`, `arrays.xml`, or other resource files |
+| **Overwrite** | Each run replaces the entire `strings.xml` in each locale folder with a fresh LLM translation |
+| **Folder scan** | Without `--languages`, every `values-*` folder is treated as a locale. Qualifier-only folders like `values-night` or `values-sw600dp` may be picked up incorrectly — prefer `--languages` or keep only locale folders in `res/` |
+| **Network** | `translate` requires internet access to reach the LLM API (except local `custom` providers) |
+| **JDK** | `verify` requires `javac` on your PATH |
+
+---
+
+## Troubleshooting
+
+| Problem | What to try |
+|---|---|
+| `Could not find English strings.xml` | Check `--res-dir` points to your `res/` folder and `values/strings.xml` exists |
+| `No locale directories found` | Add `--languages hi,es,fr` or create `values-<lang>/` folders manually |
+| API auth errors | Confirm your key env var or `--api-key` matches the `--provider` |
+| `javac` not found | Install a JDK or run `verify` from Android Studio's terminal |
+| Build fails on apostrophes | Run `android-localise fix` before building |
+| `%` crashes at runtime | Run `android-localise verify` — it catches bad format specifiers before release |
+| Wrong folder translated | Use `--languages` to target exact locale codes instead of folder scan |
+
+---
+
 ## Roadmap
 
 - [ ] **iOS support** — translate `Localizable.strings` and `Localizable.xcstrings` for iOS/macOS apps. The LLM prompt and provider logic is already in place — it mainly needs a parser for Apple's strings format and the right folder structure (`<lang>.lproj/`). Good first contribution if you're familiar with iOS projects.
+- [ ] **Smarter locale folder detection** — skip non-locale `values-*` qualifiers (`night`, `sw600dp`, `v21`, etc.) when scanning without `--languages`
+- [ ] **Automated test suite** — unit tests for `fix`, XML parsing, and format-specifier edge cases
+- [ ] **Cross-platform verification** — confirm `translate`, `fix`, and `verify` on macOS and Linux (Windows is maintainer-tested today)
 
 ---
 
 ## Contributing
 
-Bug reports and pull requests are welcome. For larger changes, open an issue first.
+Bug reports, pull requests, and **cross-platform testing** are all welcome. For larger changes, open an issue first.
+
+**No code required** — if you are on macOS or Linux, running the tool and filing an issue (pass or fail) is a real contribution. See [Platform support](#platform-support).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, branch strategy, and release process.
 
 ```bash
 git clone https://github.com/BharathKmalviya/android-llm-localization
 cd android-llm-localization
+git checkout dev
 pip install -e .
 ```
 
-Releases are automated via GitHub Actions — bump the version in `pyproject.toml` and `__init__.py`, update `CHANGELOG.md`, and push to `master`.
+Day-to-day work happens on the `dev` branch. Releases are merged to `master` via pull request, which triggers automated PyPI publishing.
+
+---
+
+## Security
+
+To report a security vulnerability, see [SECURITY.md](SECURITY.md). Please do not open public issues for security-sensitive reports.
 
 ---
 

{android_localisation-1.0.4 → android_localisation-1.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "android-localisation"
-version = "1.0.4"
+version = "1.0.5"
 description = "Zero-dependency Android strings.xml translation and verification using LLMs (Gemini, OpenAI, Anthropic, Ollama)."
 readme = "README.md"
 license = { text = "MIT" }