android-localisation 1.0.0__py3-none-any.whl

android_localisation/__init__.py

@@ -0,0 +1,5 @@
+"""
+android-localisation: Zero-dependency Android strings.xml translation using LLMs.
+"""
+
+__version__ = "1.0.0"

android_localisation/cli.py

@@ -0,0 +1,82 @@
+"""
+Unified CLI entry point for android-localisation.
+
+Usage:
+    android-localise translate --api-key KEY
+    android-localise fix
+    android-localise verify
+    android-localise models
+"""
+
+import argparse
+from android_localisation import __version__
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="android-localise",
+        description="Zero-dependency Android strings.xml localization using LLMs.",
+    )
+    parser.add_argument("--version", action="version", version=f"android-localisation {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+    subparsers.required = True
+
+    # --- translate ---
+    translate_parser = subparsers.add_parser("translate", help="Translate strings.xml into all locale directories")
+    translate_parser.add_argument("--res-dir", default="app/src/main/res", help="Path to the Android res/ directory (default: app/src/main/res)")
+    translate_parser.add_argument("--provider", choices=["gemini", "openai", "anthropic", "custom"], default="gemini", help="AI provider (default: gemini)")
+    translate_parser.add_argument("--model", help="Any model name supported by the provider (uses provider default if not set)")
+    translate_parser.add_argument("--api-key", help="API key (or set GEMINI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY)")
+    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)")
+
+    # --- fix ---
+    fix_parser = subparsers.add_parser("fix", help="Fix XML escaping issues in translated strings.xml files")
+    fix_parser.add_argument("--res-dir", default="app/src/main/res", help="Path to the Android res/ directory (default: app/src/main/res)")
+
+    # --- verify ---
+    verify_parser = subparsers.add_parser("verify", help="Verify translated strings won't crash the app (requires javac)")
+    verify_parser.add_argument("--res-dir", default="app/src/main/res", help="Path to the Android res/ directory (default: app/src/main/res)")
+
+    # --- models ---
+    models_parser = subparsers.add_parser("models", help="List all available models per provider")
+    models_parser.add_argument("--provider", choices=["gemini", "openai", "anthropic"], default=None,
+                               help="Filter by provider (shows all if not set)")
+
+    args = parser.parse_args()
+
+    if args.command == "translate":
+        from android_localisation.translate import main as run
+        run(args)
+
+    elif args.command == "fix":
+        from android_localisation.fix import main as run
+        run(args)
+
+    elif args.command == "verify":
+        from android_localisation.verify import main as run
+        run(args)
+
+    elif args.command == "models":
+        from android_localisation.translate import PROVIDER_MODELS
+        providers = [args.provider] if args.provider else ["gemini", "openai", "anthropic"]
+        print()
+        for p in providers:
+            models = PROVIDER_MODELS.get(p, [])
+            print(f"  {p.upper()}")
+            for i, m in enumerate(models):
+                tag = " (default)" if i == 0 else f" (fallback {i})" if i < len(models) - 1 else " (fallback)"
+                print(f"    {'→' if i == 0 else ' '} {m}{tag}")
+            print()
+        print("  CUSTOM (Ollama, LM Studio, etc.)")
+        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()
+
+
+if __name__ == "__main__":
+    main()

android_localisation/fix.py

@@ -0,0 +1,84 @@
+import os
+import re
+import glob
+import argparse
+
+# Matches any valid Java/Android format specifier:
+# e.g. %s, %d, %f, %1$s, %2$d, %1$f, %-10s, %+d, etc.
+_FORMAT_SPECIFIER = re.compile(
+    r'%(\d+\$)?([-#+ 0,(<]*)?(\d+)?(\.\d+)?([tT]?[a-zA-Z])'
+)
+
+# Recognizes valid specifier suffixes so we don't double-escape them
+_VALID_SPECIFIER = re.compile(
+    r'%(\d+\$)?([-#+ 0,(<]*)?(\d+)?(\.\d+)?([tT]?[a-zA-Z%])'
+)
+
+
+def _fix_text(text):
+    # Replace unicode curly apostrophes (common LLM hallucination)
+    for curly in ('\u2019', '\u2018'):
+        text = text.replace(curly, r"\'")
+
+    # Unescape java-style unicode percent signs so we can process them uniformly
+    text = text.replace(r'\u0025', '%')
+
+    # Escape unescaped apostrophes (negative lookbehind to avoid double-escaping)
+    text = re.sub(r"(?<!\\)'", r"\'", text)
+
+    # Fix % symbols:
+    # 1. Preserve valid format specifiers by replacing them with a placeholder
+    placeholders = []
+    def save_specifier(m):
+        placeholders.append(m.group(0))
+        return f"\x00FMTSPEC{len(placeholders) - 1}\x00"
+
+    text = _VALID_SPECIFIER.sub(save_specifier, text)
+
+    # 2. Any remaining bare % must be a literal — escape it
+    text = text.replace('%', '%%')
+
+    # 3. Restore the real format specifiers
+    for i, spec in enumerate(placeholders):
+        text = text.replace(f"\x00FMTSPEC{i}\x00", spec)
+
+    return text
+
+
+def _parse_args(args=None):
+    parser = argparse.ArgumentParser(description="Fix common string formatting issues in Android strings.xml files.")
+    parser.add_argument("--res-dir", default="app/src/main/res", help="Path to the Android res/ directory")
+    return parser.parse_args(args)
+
+
+def main(args=None):
+    if args is None or isinstance(args, list):
+        args = _parse_args(args)
+
+    res_dir = args.res_dir
+    print(f"Fixing strings in: {res_dir}")
+    files = glob.glob(os.path.join(res_dir, "values-*", "strings.xml"))
+    fixed_count = 0
+
+    for xml_file in files:
+        with open(xml_file, 'r', encoding='utf-8') as f:
+            content = f.read()
+
+        def fix_match(m):
+            return m.group(1) + _fix_text(m.group(2)) + m.group(3)
+
+        new_content = re.sub(
+            r'(<string[^>]*name="[^"]*"[^>]*>)(.*?)(</string>)',
+            fix_match, content, flags=re.DOTALL
+        )
+
+        if content != new_content:
+            with open(xml_file, 'w', encoding='utf-8') as f:
+                f.write(new_content)
+            fixed_count += 1
+
+    print(f"Done fixing strings. Fixed {fixed_count} files out of {len(files)}.")
+
+
+if __name__ == "__main__":
+    main()

android_localisation/java/VerifyStrings.java

@@ -0,0 +1,148 @@
+import java.io.*;
+import java.util.*;
+import java.util.regex.*;
+
+/**
+ * Utility to verify that all translated Android strings containing format specifiers 
+ * (like %1$d or %s) are syntactically valid and won't throw an UnknownFormatConversionException 
+ * or MissingFormatArgumentException at runtime.
+ */
+public class VerifyStrings {
+    
+    public static void main(String[] args) throws Exception {
+        String resDirPath = "app/src/main/res";
+        if (args.length > 0) {
+            resDirPath = args[0];
+        }
+
+        File resDir = new File(resDirPath);
+        if (!resDir.exists()) {
+            // Try relative to scripts if the absolute/relative failed
+            File fallback = new File("../" + resDirPath);
+            if (fallback.exists()) {
+                resDir = fallback;
+            }
+        }
+        
+        if (!resDir.exists()) {
+            System.err.println("Fatal: Could not find resource directory at: " + resDirPath);
+            System.exit(1);
+        }
+
+        File englishDir = new File(resDir, "values");
+        File[] valuesDirs = resDir.listFiles((dir, name) -> name.startsWith("values-"));
+        
+        if (valuesDirs == null || valuesDirs.length == 0) {
+            System.err.println("No values- localized directories found!");
+            return;
+        }
+
+        System.out.println("Started Android String Format Verification...");
+        System.out.println("Scanning source strings in: " + englishDir.getPath());
+
+        // 1. First parse the English strings to know the expected format arguments
+        Map<String, String> englishStrings = parseStringsFile(new File(englishDir, "strings.xml"));
+        Map<String, List<String>> expectedFormats = new HashMap<>();
+        
+        // Regex for Android / Java format specifiers
+        Pattern formatPattern = Pattern.compile("%(\\d+\\$)?([-#+ 0,(<]*)?(\\d+)?(\\.\\d+)?([tT]?[a-zA-Z%])");
+        for (Map.Entry<String, String> entry : englishStrings.entrySet()) {
+            List<String> formats = new ArrayList<>();
+            Matcher m = formatPattern.matcher(entry.getValue());
+            while (m.find()) {
+                formats.add(m.group());
+            }
+            expectedFormats.put(entry.getKey(), formats);
+        }
+
+        int totalErrors = 0;
+        int totalStringsVerified = 0;
+
+        // 2. Now verify every language against Android String formatting rules
+        for (File dir : valuesDirs) {
+            File stringsFile = new File(dir, "strings.xml");
+            if (!stringsFile.exists()) continue;
+
+            Map<String, String> localizedStrings = parseStringsFile(stringsFile);
+            
+            for (Map.Entry<String, String> entry : localizedStrings.entrySet()) {
+                String name = entry.getKey();
+                String text = entry.getValue();
+                totalStringsVerified++;
+
+                List<String> englishFormats = expectedFormats.get(name);
+                if (englishFormats == null || englishFormats.isEmpty()) {
+                    // This string shouldn't have any format arguments.
+                    // If it has a %, it must be %%
+                    if (text.contains("%") && !text.matches("^(?:[^%]|%%)*$")) {
+                        System.err.println("ERROR: [" + dir.getName() + "] String '" + name + "' contains unescaped % but English doesn't use formatting.");
+                        System.err.println("  Text: " + text);
+                        totalErrors++;
+                    }
+                    continue;
+                }
+
+                // Try to format it via java natively
+                try {
+                    // Provide generic arguments to satisfy any index like %1$s, %1$d.
+                    // Our app primarily uses integers and strings up to 3 parameters.
+                    String.format(text, 100, "test_string", 50);
+                } catch (UnknownFormatConversionException e) {
+                    System.err.println("CRASH: [" + dir.getName() + "] String '" + name + "' has an invalid conversion specifier: " + e.getConversion());
+                    System.err.println("  Text: " + text);
+                    totalErrors++;
+                } catch (MissingFormatArgumentException e) {
+                    System.err.println("CRASH: [" + dir.getName() + "] String '" + name + "' is missing format arguments or index is wrong: " + e.getFormatSpecifier());
+                    System.err.println("  Text: " + text);
+                    totalErrors++;
+                } catch (IllegalFormatConversionException e) {
+                    System.err.println("CRASH: [" + dir.getName() + "] String '" + name + "' uses wrong variable type logic (e.g. used %d instead of %s): " + e.getMessage());
+                    System.err.println("  Text: " + text);
+                    System.err.println("  English expected: " + englishStrings.get(name));
+                    totalErrors++;
+                } catch (Exception e) {
+                    System.err.println("CRASH: [" + dir.getName() + "] String '" + name + "' failed native String.format() -> " + e.getClass().getSimpleName() + ": " + e.getMessage());
+                    System.err.println("  Text: " + text);
+                    totalErrors++;
+                }
+            }
+        }
+
+        System.out.println("Verification Complete!");
+        System.out.println("Total Strings Verified: " + totalStringsVerified);
+        
+        if (totalErrors > 0) {
+            System.out.println("Total Errors Found: " + totalErrors);
+            System.err.println("Verification Failed!");
+            System.exit(1);
+        } else {
+            System.out.println("Status: ALL STRINGS PASSED!");
+            System.exit(0);
+        }
+    }
+
+    private static Map<String, String> parseStringsFile(File file) throws Exception {
+        Map<String, String> strings = new HashMap<>();
+        BufferedReader reader = new BufferedReader(new FileReader(file));
+        StringBuilder sb = new StringBuilder();
+        String line;
+        while ((line = reader.readLine()) != null) {
+            sb.append(line).append("\n");
+        }
+        reader.close();
+
+        // This regex ensures we only grab actual text contents inside `<string>`
+        Pattern stringPattern = Pattern.compile("<string name=\"([^\"]+)\"[^>]*>(.*?)</string>", Pattern.DOTALL);
+        Matcher m = stringPattern.matcher(sb.toString());
+        while (m.find()) {
+            String name = m.group(1);
+            String text = m.group(2);
+            // Decode standard XML entity things that AAPT2 does automatically
+            text = text.replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&");
+            // Unescape apostrophes and quotes as Java expects clean strings
+            text = text.replace("\\'", "'").replace("\\\"", "\"");
+            strings.put(name, text);
+        }
+        return strings;
+    }
+}

android_localisation/translate.py

@@ -0,0 +1,307 @@
+import os
+import time
+import argparse
+import urllib.request
+import urllib.error
+import json
+
+DEFAULT_RES_DIR = "app/src/main/res"
+API_TIMEOUT = 60  # seconds
+
+# 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-2.5-flash",
+        "gemini-2.0-flash",
+        "gemini-1.5-flash",
+        "gemini-1.5-pro",
+    ],
+    "openai": [
+        "gpt-4o-mini",
+        "gpt-4o",
+        "gpt-3.5-turbo",
+    ],
+    "anthropic": [
+        "claude-3-5-haiku-latest",
+        "claude-3-5-sonnet-latest",
+        "claude-3-opus-latest",
+    ],
+    "custom": [],  # user must specify --model
+}
+
+
+def get_target_directories(res_dir):
+    """Finds all values-* directories inside the provided res/ directory."""
+    dirs = []
+    if not os.path.exists(res_dir):
+        return dirs
+    for d in os.listdir(res_dir):
+        if d.startswith("values-") and os.path.isdir(os.path.join(res_dir, d)):
+            dirs.append(d)
+    return sorted(dirs)
+
+
+def read_source_xml(source_path):
+    with open(source_path, "r", encoding="utf-8") as f:
+        return f.read()
+
+
+def build_prompt(source_xml, target_folder_name, app_context):
+    context_str = f"an Android app ({app_context})" if app_context else "an Android application"
+    return f"""You are a professional mobile app localization expert.
+
+I am sending you the complete English `strings.xml` for {context_str}.
+Your job is to translate it into the language corresponding to the Android resource directory: `{target_folder_name}`.
+For example, `values-hi` is Hindi, `values-es-rES` is Spanish (Spain), `values-zh-rTW` is Traditional Chinese, etc.
+
+STRICT GUIDELINES:
+1. Preserve the exact meaning and intent of the English text.
+2. The language must be clear, natural, human-sounding, and understandable by all users (from rural to tier-1 cities).
+3. Do not sound like a machine translation. Use simple, everyday mobile UI language.
+4. NEVER modify string keys, XML structure, placeholders (like %s, %1$d), escape characters, \\n line breaks, or HTML tags.
+5. Keep it short and UI friendly.
+6. Return ONLY the raw updated XML content. Do not add markdown formatting like ```xml or any conversational text.
+
+SOURCE XML:
+{source_xml}
+"""
+
+
+def clean_xml_response(result):
+    if not result:
+        return ""
+    result = result.strip()
+    if result.startswith("```xml"):
+        result = result[6:]
+    if result.startswith("```"):
+        result = result[3:]
+    if result.endswith("```"):
+        result = result[:-3]
+    return result.strip()
+
+
+def _read_error_body(e):
+    try:
+        return e.read().decode("utf-8", errors="replace")[:500]
+    except Exception:
+        return "(could not read error body)"
+
+
+def _is_model_not_found(http_code, body):
+    """Returns True if the error clearly means the model doesn't exist."""
+    if http_code == 404:
+        return True
+    body_lower = body.lower()
+    return any(phrase in body_lower for phrase in [
+        "model not found", "model_not_found", "does not exist",
+        "no such model", "unknown model", "invalid model",
+    ])
+
+
+def call_gemini(api_key, model, prompt):
+    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}")
+        return None, model_gone
+
+
+def call_openai_compatible(api_key, base_url, model, prompt):
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {api_key or ''}",
+    }
+    data = {
+        "model": model,
+        "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}")
+        return None, model_gone
+
+
+def call_anthropic(api_key, model, prompt):
+    url = "https://api.anthropic.com/v1/messages"
+    headers = {
+        "Content-Type": "application/json",
+        "x-api-key": api_key,
+        "anthropic-version": "2023-06-01",
+    }
+    data = {
+        "model": model,
+        "max_tokens": 4096,
+        "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}")
+        return None, model_gone
+
+
+def _call_provider(provider, api_key, model, prompt, base_url=None):
+    """Dispatches to the right API. Returns (text, model_not_found)."""
+    if provider == "gemini":
+        return call_gemini(api_key, model, prompt)
+    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)
+    elif provider == "anthropic":
+        return call_anthropic(api_key, model, prompt)
+    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):
+    """
+    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.
+    Returns (translated_xml, model_used).
+    """
+    prompt = build_prompt(source_xml, target_folder_name, app_context)
+    models_to_try = [model] + (fallback_models or [])
+
+    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)
+        if result is not None:
+            return clean_xml_response(result), attempt_model
+        if not model_not_found:
+            # Failed for a non-model reason (auth, quota, network) — don't try fallbacks
+            return None, attempt_model
+
+    return None, models_to_try[-1]
+
+
+def _parse_args(args=None):
+    parser = argparse.ArgumentParser(description="Translate Android strings.xml using LLMs.")
+    parser.add_argument("--res-dir", default=DEFAULT_RES_DIR)
+    parser.add_argument("--provider", choices=["gemini", "openai", "anthropic", "custom"], default="gemini")
+    parser.add_argument("--model", help="Any model name for the chosen provider. Uses provider default if not set.")
+    parser.add_argument("--api-key")
+    parser.add_argument("--base-url")
+    parser.add_argument("--app-context")
+    parser.add_argument("--sleep", type=float, default=5.0)
+    return parser.parse_args(args)
+
+
+def main(args=None):
+    if args is None or isinstance(args, list):
+        args = _parse_args(args)
+
+    provider = args.provider
+    user_pinned_model = bool(args.model)  # True if user explicitly chose a model
+
+    # Resolve model + fallback chain
+    if args.model:
+        # User pinned a specific model — use it, no fallbacks
+        model = args.model
+        fallback_models = []
+    else:
+        if provider == "custom":
+            print("❌ ERROR: You must specify --model when using a custom provider.")
+            return
+        model_list = PROVIDER_MODELS.get(provider, [])
+        model = model_list[0] if model_list else None
+        fallback_models = model_list[1:]
+
+    # Resolve API key
+    api_key = args.api_key
+    if not api_key:
+        if provider == "gemini":                  api_key = os.environ.get("GEMINI_API_KEY")
+        elif provider in ("openai", "custom"):    api_key = os.environ.get("OPENAI_API_KEY")
+        elif provider == "anthropic":             api_key = os.environ.get("ANTHROPIC_API_KEY")
+        if not api_key:
+            api_key = os.environ.get("API_KEY")
+
+    if not api_key and provider != "custom":
+        print("❌ ERROR: Please provide an API key via --api-key or the appropriate environment variable.")
+        return
+
+    if provider == "custom" and not args.base_url:
+        print("❌ ERROR: You must provide --base-url when using a custom provider.")
+        return
+
+    res_dir = args.res_dir
+    source_strings_xml = os.path.join(res_dir, "values", "strings.xml")
+
+    print(f"🔍 Reading source XML from: {source_strings_xml}")
+    if not os.path.exists(source_strings_xml):
+        print("❌ ERROR: Could not find English strings.xml at the specified path.")
+        return
+
+    source_xml = read_source_xml(source_strings_xml)
+    target_dirs = get_target_directories(res_dir)
+
+    if not target_dirs:
+        print(f"⚠️  No values-* localized directories found in {res_dir}")
+        return
+
+    print(f"🌍 Found {len(target_dirs)} language directories.")
+    fallback_note = "" if user_pinned_model else f" (fallbacks: {', '.join(fallback_models)})" if fallback_models else ""
+    print(f"🤖 Provider: {provider.upper()} | Model: {model}{fallback_note}")
+
+    actual_provider = "openai" if provider == "custom" else provider
+
+    for folder in target_dirs:
+        target_path = os.path.join(res_dir, folder, "strings.xml")
+        print(f"⏳ Translating for {folder}...")
+
+        translated_xml, used_model = translate_xml(
+            actual_provider, api_key, model, source_xml,
+            folder, args.app_context, args.base_url, fallback_models
+        )
+
+        if translated_xml and "<resources>" in translated_xml and "</resources>" in translated_xml:
+            os.makedirs(os.path.dirname(target_path), exist_ok=True)
+            with open(target_path, "w", encoding="utf-8") as f:
+                f.write(translated_xml)
+            suffix = f" (via {used_model})" if used_model != model else ""
+            print(f"✅ Saved translated strings.xml to {folder}{suffix}")
+        else:
+            print(f"⚠️  Failed or got invalid XML for {folder}. Skipping.")
+
+        if args.sleep > 0:
+            time.sleep(args.sleep)
+
+    print("\n🎉 Translation process completed!")
+
+
+if __name__ == "__main__":
+    main()

android_localisation/verify.py

@@ -0,0 +1,56 @@
+import os
+import subprocess
+import sys
+import argparse
+
+
+def _parse_args(args=None):
+    parser = argparse.ArgumentParser(description="Verify Android strings formatting.")
+    parser.add_argument("--res-dir", default="app/src/main/res", help="Path to the Android res/ directory")
+    return parser.parse_args(args)
+
+
+def main(args=None):
+    if args is None or isinstance(args, list):
+        args = _parse_args(args)
+
+    package_dir = os.path.dirname(os.path.abspath(__file__))
+    java_file = os.path.join(package_dir, "java", "VerifyStrings.java")
+    java_out_dir = os.path.join(package_dir, "java")
+    project_root = os.getcwd()
+
+    if not os.path.exists(java_file):
+        print(f"[!] ERROR: Java verifier not found at {java_file}")
+        print("    This may indicate a broken installation. Try:")
+        print("      pip install --force-reinstall android-localisation")
+        sys.exit(1)
+
+    # 1. Compile the Java verifier
+    print("Compiling VerifyStrings.java...")
+    try:
+        subprocess.run(["javac", "-d", java_out_dir, java_file], check=True)
+    except FileNotFoundError:
+        print("\n[!] ERROR: 'javac' command not found.")
+        print("    Please ensure you have a Java JDK installed and 'javac' is in your system PATH.")
+        print("    Alternatively, run this from the Terminal inside Android Studio.")
+        sys.exit(1)
+    except subprocess.CalledProcessError:
+        print("Failed to compile VerifyStrings.java")
+        sys.exit(1)
+
+    # 2. Run the Java verifier
+    print(f"Running String Verifier against {args.res_dir}...")
+    run_result = subprocess.run(
+        ["java", "-cp", java_out_dir, "VerifyStrings", args.res_dir],
+        cwd=project_root
+    )
+
+    if run_result.returncode != 0:
+        print("\n[!] VERIFICATION FAILED: Found broken string formatting that could crash the app.")
+        sys.exit(run_result.returncode)
+    else:
+        print("\n[+] VERIFICATION PASSED: All localizations are syntactically safe.")
+
+
+if __name__ == "__main__":
+    main()

android_localisation-1.0.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: android-localisation
+Version: 1.0.0
+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
+Project-URL: Repository, https://github.com/BharathKmalviya/android-llm-localization
+Project-URL: Issues, https://github.com/BharathKmalviya/android-llm-localization/issues
+Project-URL: Changelog, https://github.com/BharathKmalviya/android-llm-localization/blob/master/CHANGELOG.md
+Keywords: android,localisation,localization,strings,translation,llm,gemini,openai,anthropic,ollama,i18n,l10n
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Internationalization
+Classifier: Topic :: Software Development :: Localization
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Android LLM Localization
+
+[![PyPI version](https://img.shields.io/pypi/v/android-localisation.svg)](https://pypi.org/project/android-localisation/)
+[![Python 3.8+](https://img.shields.io/pypi/pyversions/android-localisation.svg)](https://pypi.org/project/android-localisation/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/BharathKmalviya/android-llm-localization/blob/master/LICENSE)
+
+A zero-dependency Python tool to translate, fix, and verify Android `strings.xml` resources using Large Language Models (LLMs) — Gemini, OpenAI, Anthropic (Claude), or any local model via Ollama.
+
+## Why this exists?
+
+Localizing Android apps usually involves paying for services, exporting CSVs, or manually using Google Translate. This tool translates `strings.xml` directly in your project using modern LLMs, giving significantly better context-aware translations.
+
+**Zero dependencies** — no `pip install` of extra libraries required. Uses only Python's built-in networking.
+
+---
+
+## Installation
+
+```bash
+pip install android-localisation
+```
+
+To update to the latest version:
+
+```bash
+pip install --upgrade android-localisation
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Translate (Gemini free tier recommended)
+android-localise translate --api-key YOUR_GEMINI_API_KEY
+
+# 2. Fix any XML escaping issues introduced by the LLM
+android-localise fix
+
+# 3. Verify no format specifiers were corrupted (requires Java JDK)
+android-localise verify
+```
+
+---
+
+## The Three Commands
+
+### 1. `translate` — Translate strings into all locale directories
+
+Reads `app/src/main/res/values/strings.xml` (English) and writes translated `strings.xml` into every `values-*` directory it finds.
+
+**Prerequisites:**
+- Create empty `values-<lang>/` folders for each language you want (e.g. `values-hi/`, `values-es/`)
+- Get an API key — **[Google Gemini AI Studio](https://aistudio.google.com/) has a generous free tier**
+
+```bash
+# Basic — Gemini (default)
+android-localise translate --api-key YOUR_GEMINI_API_KEY
+
+# With app context for better translations
+android-localise translate --api-key YOUR_KEY --app-context "a fitness tracking app"
+
+# OpenAI
+android-localise translate --api-key YOUR_KEY --provider openai --model gpt-4o
+
+# Anthropic (Claude)
+android-localise translate --api-key YOUR_KEY --provider anthropic
+
+# Local model via Ollama
+android-localise translate --provider custom --base-url http://localhost:11434/v1/chat/completions --model llama3
+```
+
+**Full arguments:**
+
+| Argument | Description | Default |
+|---|---|---|
+| `--api-key` | API key (or set `GEMINI_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` env vars) | *None* |
+| `--provider` | AI provider: `gemini`, `openai`, `anthropic`, `custom` | `gemini` |
+| `--model` | Model name (e.g. `gemini-2.5-flash`, `gpt-4o`, `claude-3-5-sonnet-latest`) | provider default |
+| `--app-context` | Short description of your app to improve translation quality | *None* |
+| `--res-dir` | Path to the Android `res/` directory | `app/src/main/res` |
+| `--base-url` | Base URL for custom OpenAI-compatible endpoints | *None* |
+| `--sleep` | Seconds between requests to avoid rate limits | `5.0` |
+
+---
+
+### 2. `fix` — Fix XML escaping issues
+
+LLMs occasionally introduce malformed characters — curly apostrophes (`'`), unescaped quotes, or broken `%` symbols. This command cleans them all up.
+
+```bash
+android-localise fix
+# or with a custom res dir:
+android-localise fix --res-dir path/to/res
+```
+
+---
+
+### 3. `verify` — Catch format specifier crashes before they happen
+
+LLMs can corrupt Android format specifiers like `%1$s` or `%d`, which causes `UnknownFormatConversionException` crashes at runtime. This command compiles a Java verifier and dry-runs `String.format()` against every translated string.
+
+```bash
+android-localise verify
+```
+
+*Requires `javac` in your system PATH. Run from Android Studio's terminal if needed.*
+
+---
+
+## Recommended Workflow
+
+1. Update your English `strings.xml`
+2. Create empty `values-<lang>/` folders for the languages you want
+3. `android-localise translate --api-key YOUR_KEY`
+4. `android-localise fix`
+5. `android-localise verify`
+6. Build and test your app
+
+---
+
+## Supported Providers
+
+| Provider | Default Model | API Key Env Var |
+|---|---|---|
+| `gemini` (default) | `gemini-2.5-flash` | `GEMINI_API_KEY` |
+| `openai` | `gpt-4o-mini` | `OPENAI_API_KEY` |
+| `anthropic` | `claude-3-5-sonnet-latest` | `ANTHROPIC_API_KEY` |
+| `custom` | *(must specify)* | `OPENAI_API_KEY` or none |
+
+---
+
+---
+
+## Contributing
+
+Issues and PRs welcome at [github.com/BharathKmalviya/android-llm-localization](https://github.com/BharathKmalviya/android-llm-localization).
+
+---
+
+*Created to make Android localization accessible, free, and completely automated.*

android_localisation-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+android_localisation/__init__.py,sha256=QrUJ1_CLiP98-QELk2bzsjKAmDUhwyrLY6ouN2aBjzU,113
+android_localisation/cli.py,sha256=S1xLogHM7ML5rTJXifFXk_zVkoCKV8_VyVN9FVP2L8s,3857
+android_localisation/fix.py,sha256=QpN_4YLSuiB9KzDcCv5OiT5-7vwlrDw33WRq8j50HKA,2602
+android_localisation/translate.py,sha256=C8uEhNACpgntbpM6HrqNtqycMfnU0oa6UwLox4t4Duw,11838
+android_localisation/verify.py,sha256=gufTTz-ZPUarI9ZWKrsb587rH_VzWFZBjgScaUKpick,2024
+android_localisation/java/VerifyStrings.java,sha256=UeC-jmi8lYFz57-lpcLdZhozYONwARNA1gteFab_brg,6897
+android_localisation-1.0.0.dist-info/licenses/LICENSE,sha256=hMf4K6lMGkL8Fs8O0DTy1fShCwbVk63hRcOqrbKRRE0,1090
+android_localisation-1.0.0.dist-info/METADATA,sha256=b5fMj6-YRsK3IuQFC511ZpL3AAvTeiHumrWeeDfHFOA,6366
+android_localisation-1.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+android_localisation-1.0.0.dist-info/entry_points.txt,sha256=NN78HpRqDjb95Pl1ynVeU76DjQXHJXtCLgp8L-SVGO8,67
+android_localisation-1.0.0.dist-info/top_level.txt,sha256=ImH9pjj_nTP7r6SmTAZOsI36ikz4-LM9Yi23T_9YcFs,21
+android_localisation-1.0.0.dist-info/RECORD,,

android_localisation-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

android_localisation-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+android-localise = android_localisation.cli:main

android_localisation-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 android-localisation contributors
+
+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.

android_localisation-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+android_localisation