# Search by title and season/episode number
GET /api/v1/subtitles?query=The+Fosters&season_number=1&episode_number=3&languages=uk

def is_ukrainian(text):
    uk_exclusive = len(re.findall(r'[їЇєЄґҐ]', text))
    uk_i         = len(re.findall(r'[іІ]', text))
    ru_exclusive = len(re.findall(r'[ыЫэЭъЪ]', text))
    total_cyr    = len(re.findall(r'[а-яА-ЯіІїЇєЄґҐёЁыЫэЭъЪ]', text))

    if total_cyr < 20:                      return True   # too little text — don't reject
    if ru_exclusive > total_cyr * 0.02:     return False  # has "ы/э/ъ" — this is RU
    return (uk_exclusive + uk_i) > total_cyr * 0.03       # has "ї/є/і" — this is UK

def compute_sync(en_blocks, uk_blocks):
    en_t0 = parse_time(en_blocks[0][1].split('-->')[0])
    en_t1 = parse_time(en_blocks[-1][1].split('-->')[0])
    uk_t0 = parse_time(uk_blocks[0][1].split('-->')[0])
    uk_t1 = parse_time(uk_blocks[-1][1].split('-->')[0])

    scale  = (en_t1 - en_t0) / (uk_t1 - uk_t0)
    offset = en_t0 - scale * uk_t0
    return offset, scale

# ─── Ланцюжок перекладу (Chain of Responsibility) ─────────────────
# Format: "Service (fallbacks:timeout_inc) -> ..."
#   fallbacks    — retries after the first attempt (0 = one attempt only)
#   timeout_inc  — seconds added to timeout per retry
# First service = primary (Phase 1 batch). Rest = CoR fallback for failures.
# Unavailable service (not installed) → skipped automatically.
TRANSLATOR_CHAIN = "Google (2:30) -> Argos (1) -> MyMemory (1) -> LibreTranslate (1) -> Claude"

# ─── Local LibreTranslate server ──────────────────────────────────
# POST /translate  {"q": text, "source": "en", "target": "uk", "format": "text"}
# Leave "" to skip LibreTranslate entirely.
LIBRETRANSLATE_URL = "http://192.168.1.147:6455"

def _parse_chain_config(chain_str: str) -> list:
    steps = []
    for part in re.split(r'\s*->\s*', chain_str.strip()):
        # Allows spaces around colon: (1:30) or (1 : 30) or (1: 30)
        m = re.match(r'^(\w+)\s*(?:\(\s*(\d+)\s*(?::\s*(\d+)\s*)?\))?$', part.strip())
        if not m:
            continue
        steps.append({
            'name':        m.group(1),
            'fallbacks':   int(m.group(2)) if m.group(2) else 0,
            'timeout_inc': int(m.group(3)) if m.group(3) else 0,
        })
    return steps

class TranslatorStep:
    def __init__(self, name, fn, fallbacks=0, timeout_inc=0, timeout_base=30):
        self.name         = name
        self.fn           = fn
        self.fallbacks    = fallbacks    # retries after first attempt
        self.timeout_inc  = timeout_inc  # seconds added to timeout per retry
        self.timeout_base = timeout_base
        self.next: 'TranslatorStep | None' = None

    def execute(self, entries):
        remaining  = entries
        total_att  = self.fallbacks + 1
        for attempt in range(total_att):
            if not remaining:
                return
            timeout = self.timeout_base + attempt * self.timeout_inc
            label   = self.name if attempt == 0 else f"{self.name}↺{attempt}"
            print(f"  [{label}] {len(remaining)} entries...", end='', flush=True)
            result    = self.fn(remaining, timeout=timeout)
            remaining = [
                (idx, clean) for idx, clean in remaining
                if not (result.get(idx) and cyrillic_ratio(result[idx]) >= MIN_QUALITY)
            ]
        if remaining and self.next:
            self.next.execute(remaining)

# Filter out unavailable services, build linked list in config order
resolved = [s for s in _parse_chain_config(TRANSLATOR_CHAIN)
            if _check_service(s['name'], has_argos)[0]]

steps = [
    TranslatorStep(name=s['name'], fn=_FN_MAP[s['name']],
                   fallbacks=s['fallbacks'], timeout_inc=s['timeout_inc'])
    for s in resolved
]
for i in range(len(steps) - 1):
    steps[i].set_next(steps[i + 1])

# Phase 1: primary batch pass
primary_fn(all_entries, timeout=30)

# Phase 2: CoR for failures
steps[0].execute(failed_entries)

docker run -p 6455:5000 libretranslate/libretranslate

POST http://192.168.1.147:6455/translate
{"q": "text", "source": "en", "target": "uk", "format": "text", "api_key": ""}
# → {"translatedText": "переклад"}

# ~/.claude/fetch-claude-usage.swift returns "84|2026-03-28T15:00:00Z"
# where 84 = % USED tokens, so free = 100 - 84 = 16%
def get_free_tokens_pct() -> float | None:
    ...

def claude_allowed(min_pct: float) -> bool:
    if _token_pct is None:
        return True   # unknown → allow optimistically
    return _token_pct >= min_pct

python3 translate_subtitles.py 11 --min-tokens 30

| Date & Time         | Run Result                                                              |
|---------------------|-------------------------------------------------------------------------|
| 2026-03-28 21:15:33 | ✓ 4/4 | OS×2 | Google×340 | Claude×12 | OS:86/100 | tokens: 63%→51% |
| 2026-03-28 19:02:11 | ✓ 11/11 | Google×8102 | Argos×44 | OS:98/100 | tokens: 84%→71% |

# Dependencies
pip3 install deep-translator argostranslate --break-system-packages

# Download Argos offline model (optional — used as fallback)
argospm install translate-en_uk

# Local LibreTranslate (optional — used as fallback)
docker run -p 6455:5000 libretranslate/libretranslate

# Run
python3 translate_subtitles.py              # default: 30 files, 30% token threshold
python3 translate_subtitles.py 10           # process 10 files per run
python3 translate_subtitles.py --min-tokens 50    # stricter token limit
python3 translate_subtitles.py --debug-tokens     # diagnose token source