droidlate 1.0.0__py3-none-any.whl

droidlate/__init__.py

@@ -0,0 +1 @@
+# droidlate package init

droidlate/cli_wizard.py

@@ -0,0 +1,145 @@
+import os
+import sys
+import re
+
+from .parser.xml_parser import parse_strings_xml, write_string_translation
+from .parser.diff_engine import load_metadata, update_metadata_entry, categorize_key, validate_placeholders
+from .main import auto_detect_res_dir
+
+def run_wizard():
+    print("=== Droidlate: CLI Wizard ===")
+    
+    # Auto-detect res dir
+    res_dir = auto_detect_res_dir()
+    print(f"Auto-detected resource directory: {res_dir}")
+    
+    source_path = os.path.join(res_dir, "values", "strings.xml")
+    if not os.path.exists(source_path):
+        print(f"Error: Could not find base strings file at '{source_path}'.")
+        sys.exit(1)
+        
+    source_entries = parse_strings_xml(source_path)
+    if not source_entries:
+        print("Error: Base strings.xml is empty or invalid.")
+        sys.exit(1)
+        
+    # Scan for target languages
+    locales = []
+    for folder in os.listdir(res_dir):
+        folder_path = os.path.join(res_dir, folder)
+        match = re.match(r"^values-([a-z]{2,3})(?:-r([a-zA-Z]{2,4}))?$", folder)
+        if os.path.isdir(folder_path) and match:
+            target_xml = os.path.join(folder_path, "strings.xml")
+            locales.append((folder, target_xml))
+            
+    if not locales:
+        print("No localized values-* directories found.")
+        sys.exit(0)
+        
+    print("\nAvailable Locales:")
+    for idx, (folder, _) in enumerate(sorted(locales)):
+        print(f"[{idx + 1}] {folder}")
+        
+    try:
+        selection = input("\nSelect a language number to translate: ").strip()
+        sel_idx = int(selection) - 1
+        if sel_idx < 0 or sel_idx >= len(locales):
+            raise ValueError()
+    except (ValueError, KeyboardInterrupt):
+        print("\nExiting wizard.")
+        sys.exit(0)
+        
+    target_folder, target_xml = sorted(locales)[sel_idx]
+    print(f"\nLoading translations for: {target_folder}")
+    
+    # Load target entries and metadata
+    target_entries = parse_strings_xml(target_xml) if os.path.exists(target_xml) else {}
+    metadata = load_metadata(target_xml)
+    
+    metadata_changed = False
+    
+    # Warn about orphaned translation keys
+    orphaned_keys = [k for k in target_entries.keys() if k not in source_entries]
+    if orphaned_keys:
+        print(f"\n[!] Warning: Found {len(orphaned_keys)} orphaned key(s) in translation that no longer exist in English source XML.")
+        print("    Use the Web interface to safely prune them or edit the XML file manually.")
+        
+    # Auto-initialize legacy translations
+    for key, entry in source_entries.items():
+        if key in target_entries and key not in metadata:
+            from .parser.diff_engine import normalize_source_string, compute_source_hash
+            norm_src = normalize_source_string(entry.value)
+            metadata[key] = {
+                "source_hash": compute_source_hash(norm_src),
+                "translated_value": target_entries[key].value
+            }
+            metadata_changed = True
+    if metadata_changed:
+        from .parser.diff_engine import save_metadata
+        save_metadata(target_xml, metadata)
+    
+    # Filter keys needing attention (untranslated, outdated, warnings)
+    todo_keys = []
+    for key, entry in source_entries.items():
+        tgt_val = target_entries.get(key).value if key in target_entries else None
+        meta_val = metadata.get(key)
+        status = categorize_key(key, entry.value, tgt_val, meta_val)
+        
+        if status != "translated":
+            todo_keys.append((key, entry, tgt_val, status))
+            
+    if not todo_keys:
+        print("All strings are already translated and up-to-date!")
+        sys.exit(0)
+        
+    print(f"Found {len(todo_keys)} strings requiring attention.")
+    print("Commands: Type ':q' to quit, press Enter with empty text to skip.")
+    print("-" * 50)
+    
+    for idx, (key, src_entry, tgt_val, status) in enumerate(todo_keys):
+        print(f"\n[{idx + 1}/{len(todo_keys)}] Key: {key} [Status: {status.upper()}]")
+        print(f"Source: {repr(src_entry.value)}")
+        if src_entry.comment:
+            print(f"Comment: {src_entry.comment}")
+        if tgt_val is not None:
+            print(f"Current Target: {repr(tgt_val)}")
+            
+        try:
+            translation = input("Translation > ").strip()
+        except (KeyboardInterrupt, EOFError):
+            print("\nWizard interrupted. Exiting safely.")
+            break
+            
+        if translation == ":q":
+            print("Exiting wizard.")
+            break
+        elif not translation:
+            print("Skipped.")
+            continue
+            
+        # Check formatting warnings before saving
+        warnings = validate_placeholders(src_entry.value, translation)
+        if warnings:
+            print("\nWARNING: Placeholder mismatches detected:")
+            for warn in warnings:
+                print(f"  - {warn}")
+            confirm = input("Are you sure you want to save this translation? (y/N): ").strip().lower()
+            if confirm != 'y':
+                print("Skipped (not saved).")
+                continue
+                
+        print("Saving...")
+        
+        # Order of Writes: target XML first, metadata sidecar second
+        # If interrupted here, target exists but metadata does not, resolving to 'outdated' on next load.
+        write_success = write_string_translation(target_xml, key, translation, src_entry.attrib)
+        if write_success:
+            update_metadata_entry(target_xml, key, src_entry.value, translation)
+            print("Saved successfully.")
+        else:
+            print("Error saving to target XML.")
+            
+    print("\nWizard finished.")
+
+if __name__ == "__main__":
+    run_wizard()

droidlate/config.py

@@ -0,0 +1,13 @@
+import os
+
+def get_deepl_api_key() -> str:
+    """Retrieves DeepL API key from environment variables."""
+    return os.environ.get("DEEPL_API_KEY", "")
+
+def is_deepl_free_api() -> bool:
+    """Returns True if the user is using the DeepL Free API (default) or False for Pro."""
+    return os.environ.get("DEEPL_FREE_API", "true").lower() == "true"
+
+def get_default_source_lang() -> str:
+    """Returns default source language code."""
+    return os.environ.get("DEFAULT_SOURCE_LANG", "en")

droidlate/main.py

@@ -0,0 +1,123 @@
+import os
+import sys
+import argparse
+import webbrowser
+import threading
+import time
+
+from .web.server import start_web_server
+
+def auto_detect_res_dir() -> str:
+    """
+    Tries to automatically detect the Android resource directory in the current working directory.
+    Checks for typical paths like:
+    1. app/src/main/res/
+    2. src/main/res/
+    3. res/
+    If none of these are found, defaults to the current working directory.
+    """
+    cwd = os.getcwd()
+    
+    candidates = [
+        os.path.join(cwd, "app", "src", "main", "res"),
+        os.path.join(cwd, "src", "main", "res"),
+        os.path.join(cwd, "res"),
+    ]
+    
+    for candidate in candidates:
+        if os.path.exists(candidate) and os.path.isdir(candidate):
+            return candidate
+            
+    return cwd
+
+def open_browser_after_delay(url: str, delay: float = 0.5):
+    """Opens browser in a daemon thread after a brief server-warmup delay."""
+    def target():
+        time.sleep(delay)
+        webbrowser.open(url)
+    threading.Thread(target=target, daemon=True).start()
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Droidlate — A local web-based Weblate-like UI for Android strings.xml translations"
+    )
+    
+    # Resource directory scanning mode
+    parser.add_argument(
+        "--res-dir",
+        type=str,
+        help="Scan the entire Android resource directory (looks for app/src/main/res by default)"
+    )
+    
+    # Direct file editing mode
+    parser.add_argument(
+        "--source",
+        type=str,
+        help="Path to the source XML file (typically values/strings.xml)"
+    )
+    parser.add_argument(
+        "--target",
+        type=str,
+        help="Path to the target translation XML file (e.g. values-es/strings.xml)"
+    )
+    
+    # Port specification
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=5000,
+        help="Port to run the local web server on (default: 5000)"
+    )
+
+    args = parser.parse_args()
+    url = f"http://127.0.0.1:{args.port}"
+
+    # 1. Check for single-file mode
+    if args.source or args.target:
+        if not args.source or not args.target:
+            print("Error: Both --source and --target must be specified for single-file mode.", file=sys.stderr)
+            sys.exit(1)
+            
+        if not os.path.exists(args.source):
+            print(f"Error: Source file does not exist: {args.source}", file=sys.stderr)
+            sys.exit(1)
+            
+        print(f"Running Droidlate...")
+        print(f"Web server running at {url}")
+        print("Press Ctrl+C to stop.")
+        
+        # Start server in single file mode
+        start_web_server(
+            source_xml=os.path.abspath(args.source),
+            target_xml=os.path.abspath(args.target),
+            port=args.port
+        )
+        
+    # 2. Otherwise, run in resource directory mode
+    else:
+        res_dir = args.res_dir
+        if not res_dir:
+            res_dir = auto_detect_res_dir()
+            print(f"No arguments provided. Auto-detected resource directory: {res_dir}")
+
+        res_dir = os.path.abspath(res_dir)
+        source_xml = os.path.join(res_dir, "values", "strings.xml")
+        
+        if not os.path.exists(source_xml):
+            print(
+                f"Error: Could not find base strings file at '{source_xml}'.\n"
+                f"Please ensure you are running the command in an Android project root or "
+                f"specify a valid resource directory using --res-dir.",
+                file=sys.stderr
+            )
+            sys.exit(1)
+
+        print(f"Running Droidlate...")
+        print(f"Web server running at {url}")
+        print("Press Ctrl+C to stop.")
+        
+        # Start server in directory scanning mode
+        start_web_server(res_dir=res_dir, port=args.port)
+
+if __name__ == "__main__":
+    main()

droidlate/parser/__init__.py

@@ -0,0 +1 @@
+# droidlate.parser package init

droidlate/parser/diff_engine.py

@@ -0,0 +1,159 @@
+import os
+import re
+import json
+import hashlib
+
+# Re-use the placeholder regex and logic
+PLACEHOLDER_REGEX = re.compile(r'%([0-9]+\$)?[-#+ 0,\(<]*[0-9]*(\.[0-9]+)?([a-zA-Z%])')
+
+def extract_placeholders(s: str) -> list[tuple[int | None, str]]:
+    """Extracts Java/Android string format specifiers, skipping %% literals."""
+    placeholders = []
+    for match in PLACEHOLDER_REGEX.finditer(s):
+        idx_str = match.group(1)
+        ptype = match.group(3)
+        if ptype == '%':
+            continue
+        idx = int(idx_str[:-1]) if idx_str else None
+        placeholders.append((idx, ptype))
+    return placeholders
+
+def resolve_placeholders(placeholders: list[tuple[int | None, str]]) -> list[tuple[int, str]]:
+    """Resolves unmarked format placeholders to explicit positional indices."""
+    resolved = []
+    implicit_idx = 1
+    for pos, ptype in placeholders:
+        if pos is None:
+            resolved.append((implicit_idx, ptype))
+            implicit_idx += 1
+        else:
+            resolved.append((pos, ptype))
+    return resolved
+
+def validate_placeholders(source_val: str, target_val: str) -> list[str]:
+    """
+    Validates placeholder formatting between source and target values.
+    Returns a list of distinct validation warning messages (empty if valid).
+    """
+    src_pl = extract_placeholders(source_val)
+    tgt_pl = extract_placeholders(target_val)
+    
+    src_res = resolve_placeholders(src_pl)
+    tgt_res = resolve_placeholders(tgt_pl)
+    
+    src_map = {idx: t for idx, t in src_res}
+    tgt_map = {idx: t for idx, t in tgt_res}
+    
+    errors = []
+    
+    # 1. Check for missing or type mismatches
+    for idx, src_type in src_map.items():
+        if idx not in tgt_map:
+            errors.append(f"Missing placeholder %{idx}${src_type}")
+        elif tgt_map[idx] != src_type:
+            errors.append(f"Type mismatch for placeholder %{idx}: expected '{src_type}', got '{tgt_map[idx]}'")
+            
+    # 2. Check for unexpected/extra placeholders
+    for idx, tgt_type in tgt_map.items():
+        if idx not in src_map:
+            errors.append(f"Extra/unexpected placeholder %{idx}${tgt_type}")
+            
+    return errors
+
+def normalize_source_string(val: str) -> str:
+    """Normalizes string value before hashing (collapsing whitespace/newlines)."""
+    if not val:
+        return ""
+    # Collapse multiple consecutive whitespace characters to a single space
+    normalized = re.sub(r'\s+', ' ', val)
+    return normalized.strip()
+
+def compute_source_hash(normalized_val: str) -> str:
+    """Computes a SHA-256 hash of the normalized source string."""
+    return hashlib.sha256(normalized_val.encode('utf-8')).hexdigest()
+
+def get_project_root(path: str) -> str:
+    """Finds the root directory of the Android project by searching upwards."""
+    current = os.path.abspath(path)
+    if os.path.isfile(current):
+        current = os.path.dirname(current)
+        
+    while current and current != os.path.dirname(current):
+        if any(os.path.exists(os.path.join(current, marker)) for marker in ("build.gradle", "build.gradle.kts", "settings.gradle", ".git")):
+            return current
+        current = os.path.dirname(current)
+        
+    # Fallback to parent of target directory
+    return os.path.dirname(os.path.abspath(path))
+
+def get_metadata_path(target_xml_path: str) -> str:
+    """Gets the path to the centralized metadata file for a target XML."""
+    target_abs = os.path.abspath(target_xml_path)
+    project_root = get_project_root(target_abs)
+    
+    locale_folder = os.path.basename(os.path.dirname(target_abs))
+    metadata_dir = os.path.join(project_root, ".translation_metadata")
+    return os.path.join(metadata_dir, f"{locale_folder}.json")
+
+def load_metadata(target_xml_path: str) -> dict:
+    """Loads target sidecar metadata JSON file."""
+    path = get_metadata_path(target_xml_path)
+    if os.path.exists(path):
+        try:
+            with open(path, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except Exception:
+            return {}
+    return {}
+
+def save_metadata(target_xml_path: str, metadata: dict) -> None:
+    """Saves metadata dictionary to sidecar JSON file."""
+    path = get_metadata_path(target_xml_path)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    try:
+        with open(path, 'w', encoding='utf-8') as f:
+            json.dump(metadata, f, ensure_ascii=False, indent=2)
+    except Exception:
+        pass
+
+def update_metadata_entry(target_xml_path: str, key: str, source_value: str, translated_value: str) -> None:
+    """Updates a single key's metadata entry."""
+    metadata = load_metadata(target_xml_path)
+    norm_src = normalize_source_string(source_value)
+    src_hash = compute_source_hash(norm_src)
+    metadata[key] = {
+        "source_hash": src_hash,
+        "translated_value": translated_value
+    }
+    save_metadata(target_xml_path, metadata)
+
+def categorize_key(
+    key: str,
+    source_val: str,
+    target_val: str | None,
+    metadata_entry: dict | None
+) -> str:
+    """
+    Categorizes a translation key as 'untranslated', 'warnings', 'outdated', or 'translated'.
+    """
+    # 1. Untranslated check
+    if target_val is None:
+        return 'untranslated'
+
+    # 2. Warnings/Errors check
+    warnings = validate_placeholders(source_val, target_val)
+    if warnings:
+        return 'warnings'
+
+    # 3. Outdated/Modified check
+    if not metadata_entry:
+        return 'outdated'
+
+    saved_hash = metadata_entry.get("source_hash")
+    current_norm = normalize_source_string(source_val)
+    current_hash = compute_source_hash(current_norm)
+
+    if saved_hash != current_hash:
+        return 'outdated'
+
+    return 'translated'