Upload 7 files

app/renpy/extract.py

@@ -0,0 +1,134 @@
+"""Index the translatable text in an uploaded Ren'Py project.
+
+Accepts either shape people actually have: a zip of nothing but scripts, or a
+whole `game/` folder. Both are walked the same way and everything that is not
+a script is ignored, so uploading the folder costs no more time than uploading
+the scripts alone.
+
+Two directories are always skipped:
+
+  tl/     - somebody else's finished translation. Re-translating a translation
+            is the classic way to end up with a game in two languages at once.
+  renpy/  - the engine's own source, shipped inside some distributions. Its
+            strings belong to Ren'Py, not to the game.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import rpyc, script
+
+SCRIPT_SUFFIXES = (".rpy", ".rpyc")
+
+# Directory names that never hold the game's own translatable script.
+_SKIP_DIRS = {"tl", "renpy", "cache", "saves", "lib", "__pycache__"}
+
+
+@dataclass
+class Slot:
+    """One place a translation gets written back.
+
+    `start`/`end` bracket the characters between the quotes in the source
+    file. A slot from a compiled .rpyc has no writable span - the bytes cannot
+    be edited safely - so it is marked unwritable and reaches the game through
+    a generated translation file instead.
+    """
+
+    file: str
+    start: int = -1
+    end: int = -1
+    quote: str = '"'
+    writable: bool = True
+    kind: str = "dialogue"
+
+
+@dataclass
+class Unit:
+    """One source string and every place it occurs."""
+
+    source: str
+    slots: list[Slot] = field(default_factory=list)
+
+    @property
+    def occurrences(self) -> int:
+        return len(self.slots)
+
+
+def is_script(path: Path) -> bool:
+    return path.suffix.lower() in SCRIPT_SUFFIXES
+
+
+def is_skipped(relative: Path) -> bool:
+    """True when a path sits inside a directory we never read."""
+    return any(part.lower() in _SKIP_DIRS for part in relative.parts[:-1])
+
+
+def iter_scripts(root: Path):
+    """Yield every script under `root`, in a stable order."""
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or not is_script(path):
+            continue
+        relative = path.relative_to(root)
+        if is_skipped(relative):
+            continue
+        yield path, relative
+
+
+def has_scripts(root: Path) -> bool:
+    for _ in iter_scripts(root):
+        return True
+    return False
+
+
+def extract(root: Path) -> tuple[list[Unit], list[str]]:
+    """Read every script under `root`. Returns (units, unreadable_files)."""
+    by_source: dict[str, Unit] = {}
+    broken: list[str] = []
+
+    def sink(source: str, slot: Slot) -> None:
+        unit = by_source.get(source)
+        if unit is None:
+            unit = Unit(source=source)
+            by_source[source] = unit
+        unit.slots.append(slot)
+
+    for path, relative in iter_scripts(root):
+        name = relative.as_posix()
+        if path.suffix.lower() == ".rpy":
+            try:
+                source = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                try:
+                    source = path.read_text(encoding="utf-8", errors="replace")
+                except OSError:
+                    broken.append(name)
+                    continue
+            try:
+                for item in script.find_translatable(source):
+                    sink(
+                        item.text,
+                        Slot(
+                            file=name,
+                            start=item.start,
+                            end=item.end,
+                            quote=item.quote,
+                            writable=True,
+                            kind=item.kind,
+                        ),
+                    )
+            except Exception:  # noqa: BLE001 - one odd script must not stop the scan
+                broken.append(name)
+            continue
+
+        # Compiled script: readable, not writable.
+        try:
+            strings = rpyc.extract_strings(path)
+        except Exception:  # noqa: BLE001 - unknown or newer .rpyc layout
+            broken.append(name)
+            continue
+        for text, kind in strings:
+            sink(text, Slot(file=name, writable=False, kind=kind))
+
+    return list(by_source.values()), broken

app/renpy/inject.py

@@ -0,0 +1,70 @@
+"""Write translations back into .rpy scripts.
+
+A translation replaces exactly the characters between one pair of quotes and
+nothing else. Spans are applied from the end of the file backwards so that
+every offset still refers to the text it was measured against - rewriting
+front-to-back would shift each following span by the length the last one
+changed.
+
+The script around the strings is never re-indented, re-wrapped or re-parsed, so
+a file whose strings all translate to themselves comes back byte-identical.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .text import escape
+
+
+def apply_to_source(source: str, spans: list[tuple[int, int, str, str]]) -> str:
+    """Replace each (start, end, quote, translation) span in `source`."""
+    ordered = sorted(spans, key=lambda item: item[0], reverse=True)
+    out = source
+    last_start = len(source) + 1
+    for start, end, quote, translated in ordered:
+        if end > last_start:
+            # Overlapping spans would corrupt the file. The scanner cannot
+            # produce them, but a stale units.json against an edited source
+            # could, so refuse rather than write nonsense.
+            raise ValueError(f"overlapping span at {start}:{end}")
+        out = out[:start] + escape(translated, quote) + out[end:]
+        last_start = start
+    return out
+
+
+def apply(project_dir: Path, units: list, translations: dict[str, str]) -> tuple[int, int]:
+    """Write every translated unit into the scripts under `project_dir`.
+
+    Groups by file so each script is read and written once. Returns
+    (written_spans, skipped_spans).
+    """
+    by_file: dict[str, list[tuple[int, int, str, str]]] = {}
+    for unit in units:
+        translated = translations.get(unit.source)
+        if translated is None:
+            continue
+        for slot in unit.slots:
+            if not slot.writable:
+                continue
+            by_file.setdefault(slot.file, []).append(
+                (slot.start, slot.end, slot.quote, translated)
+            )
+
+    written = skipped = 0
+    for name, spans in by_file.items():
+        path = project_dir / name
+        try:
+            source = path.read_text(encoding="utf-8")
+        except OSError:
+            skipped += len(spans)
+            continue
+        try:
+            updated = apply_to_source(source, spans)
+        except ValueError:
+            skipped += len(spans)
+            continue
+        path.write_text(updated, encoding="utf-8")
+        written += len(spans)
+
+    return written, skipped

app/renpy/rpyc.py

@@ -0,0 +1,188 @@
+"""Read the dialogue out of a compiled .rpyc script.
+
+A .rpyc holds Ren'Py's parsed syntax tree, pickled and deflated. That is
+enough to *read* every line of dialogue, which is what makes it possible to
+translate a game that ships without its .rpy sources. It is not enough to write
+one back: the tree also encodes line numbers and file offsets that the engine
+checks, so translated text reaches these games through a generated translation
+file instead of an edit.
+
+Unpickling a file from a stranger normally means running their code - the
+pickle format can name any importable object and call it. This reader never
+imports anything the file asks for. Every class name it encounters is answered
+with an inert stand-in that only records the attributes assigned to it, so a
+malicious .rpyc has nothing to reach for.
+"""
+
+from __future__ import annotations
+
+import io
+import pickle
+import struct
+import zlib
+from pathlib import Path
+
+_MAGIC = b"RENPY RPC2"
+
+# Node types whose text the player reads.
+_SAY_NODES = {"Say"}
+_MENU_NODES = {"Menu"}
+# Existing translations inside the compiled file - skipping them keeps a
+# part-translated game from being translated a second time.
+_TRANSLATE_NODES = {"Translate", "TranslateString", "TranslateBlock", "TranslatePython"}
+
+_MAX_NODES = 2_000_000
+
+
+class _Stand:
+    """Inert stand-in for a class named inside the pickle."""
+
+    __slots__ = ("__dict__",)
+
+    def __init__(self, *args, **kwargs) -> None:
+        # Ren'Py reconstructs most nodes through __setstate__, but a few are
+        # built with positional arguments; keeping them lets the walker still
+        # see any strings they carry.
+        if args:
+            self.__dict__["_args"] = args
+
+    def __setstate__(self, state) -> None:
+        if isinstance(state, dict):
+            self.__dict__.update(state)
+        else:
+            self.__dict__["_state"] = state
+
+    # Pickle sometimes appends to or updates a reconstructed object.
+    def append(self, item) -> None:
+        self.__dict__.setdefault("_items", []).append(item)
+
+    def extend(self, items) -> None:
+        self.__dict__.setdefault("_items", []).extend(items)
+
+    def __setitem__(self, key, value) -> None:
+        self.__dict__.setdefault("_map", {})[key] = value
+
+
+_stand_cache: dict[tuple[str, str], type] = {}
+
+
+def _stand_for(module: str, name: str) -> type:
+    key = (module, name)
+    cached = _stand_cache.get(key)
+    if cached is None:
+        cached = type(name, (_Stand,), {"__module__": module})
+        _stand_cache[key] = cached
+    return cached
+
+
+class _SafeUnpickler(pickle.Unpickler):
+    """Unpickler that resolves every name to an inert stand-in."""
+
+    def find_class(self, module: str, name: str):
+        return _stand_for(module, name)
+
+    def persistent_load(self, pid):
+        return None
+
+
+def _slots(blob: bytes) -> dict[int, bytes]:
+    """Split an RPC2 container into its numbered slots."""
+    slots: dict[int, bytes] = {}
+    cursor = len(_MAGIC)
+    while cursor + 12 <= len(blob):
+        number, start, length = struct.unpack("<III", blob[cursor : cursor + 12])
+        cursor += 12
+        if number == 0:
+            break
+        if start + length > len(blob):
+            raise ValueError("slot runs past end of file")
+        slots[number] = blob[start : start + length]
+    return slots
+
+
+def _load_tree(path: Path):
+    blob = path.read_bytes()
+    if blob.startswith(_MAGIC):
+        slots = _slots(blob)
+        # Slot 1 carries the syntax tree in every version that uses this
+        # container; the others hold source and metadata.
+        payload = slots.get(1)
+        if payload is None:
+            raise ValueError("no syntax-tree slot in .rpyc")
+        data = zlib.decompress(payload)
+    else:
+        # Ren'Py 6.17 and older: the whole file is one deflated pickle.
+        data = zlib.decompress(blob)
+    return _SafeUnpickler(io.BytesIO(data)).load()
+
+
+def _walk(node, sink, seen: set[int], budget: list[int]) -> None:
+    """Collect dialogue from the object graph, depth first."""
+    if budget[0] <= 0:
+        return
+    budget[0] -= 1
+
+    if isinstance(node, (str, bytes, int, float, bool, type(None))):
+        return
+
+    marker = id(node)
+    if marker in seen:
+        return
+    seen.add(marker)
+
+    if isinstance(node, dict):
+        for value in node.values():
+            _walk(value, sink, seen, budget)
+        return
+    if isinstance(node, (list, tuple, set, frozenset)):
+        for value in node:
+            _walk(value, sink, seen, budget)
+        return
+
+    fields = getattr(node, "__dict__", None)
+    if not isinstance(fields, dict):
+        return
+
+    kind = type(node).__name__
+
+    if kind in _TRANSLATE_NODES:
+        # The body of a translate node *is* an existing translation. Reading it
+        # would feed a finished translation back through the model, so the
+        # whole subtree is left unread - the untranslated original is still in
+        # the script as an ordinary Say node.
+        return
+
+    if kind in _SAY_NODES:
+        what = fields.get("what")
+        if isinstance(what, str):
+            sink(what, "dialogue")
+
+    elif kind in _MENU_NODES:
+        items = fields.get("items")
+        if isinstance(items, (list, tuple)):
+            for item in items:
+                if isinstance(item, (list, tuple)) and item and isinstance(item[0], str):
+                    sink(item[0], "menu")
+
+    for value in fields.values():
+        _walk(value, sink, seen, budget)
+
+
+def extract_strings(path: Path) -> list[tuple[str, str]]:
+    """Return (text, kind) for every readable line of dialogue in a .rpyc."""
+    tree = _load_tree(path)
+    out: list[tuple[str, str]] = []
+    seen_text: set[str] = set()
+
+    def sink(text: str, kind: str) -> None:
+        if not text.strip() or text in seen_text:
+            return
+        from .text import is_translatable
+
+        if not is_translatable(text):
+            return
+        seen_text.add(text)
+        out.append((text, kind))
+
+    _walk(tree, sink, set(), [_MAX_NODES])
+    return out

app/renpy/script.py

@@ -0,0 +1,396 @@
+"""Find the translatable strings in a .rpy script, with exact source offsets.
+
+Ren'Py scripts mix dialogue with executable Python, asset filenames, style
+definitions and screen layout in one file, and the difference between them is
+the difference between a translated game and a game that will not start. So
+this parser is built to be *certain* about what it touches:
+
+* Every string literal in the file is located in one pass that understands
+  comments, escapes and triple quotes. Nothing downstream ever re-scans raw
+  text, so a `#` inside dialogue or a quote inside a comment cannot shift an
+  offset.
+* Statements are classified from a "code view" of each line - the same line
+  with the inside of every string blanked out - so a keyword mentioned inside
+  dialogue is never mistaken for the statement's own keyword.
+* Anything not positively recognised as dialogue, a menu choice or screen text
+  is left alone. Over-skipping costs a line of translation; under-skipping
+  corrupts a script.
+
+The offsets are what makes writing back safe: a translation replaces exactly
+the characters between one pair of quotes, so no amount of re-flowing by the
+model can disturb the code around it.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .text import EscapeError, is_translatable, unescape
+
+# Statements whose entire indented body holds no dialogue. Skipping the block
+# outright is safer than trusting per-line rules inside it: `style` bodies name
+# fonts, `image` bodies name files, `python` bodies are code, and `translate`
+# bodies are somebody else's finished translation.
+_BLOCK_SKIP = {
+    "python",
+    "init",
+    "style",
+    "transform",
+    "image",
+    "layeredimage",
+    "testcase",
+    "translate",
+    "camera",
+}
+
+# Single statements that carry no dialogue. Their arguments are label names,
+# asset paths, transitions or expressions.
+_LINE_SKIP = {
+    "define",
+    "default",
+    "jump",
+    "call",
+    "scene",
+    "show",
+    "hide",
+    "with",
+    "play",
+    "stop",
+    "queue",
+    "voice",
+    "pause",
+    "return",
+    "pass",
+    "window",
+    "nvl",
+    "use",
+    "add",
+    "on",
+    "key",
+    "timer",
+    "imagemap",
+    "hotspot",
+    "hotbar",
+    "drag",
+    "draggroup",
+    "mousearea",
+    "imagebutton",
+    "input",
+    "bar",
+    "vbar",
+    "viewport",
+    "side",
+    "grid",
+    "vpgrid",
+    "fixed",
+    "hbox",
+    "vbox",
+    "frame",
+    "null",
+    "has",
+    "at",
+    "audio",
+    "sound",
+    "music",
+    "movie",
+    "transclude",
+    "default_focus",
+}
+
+# Screen statements whose *first* string is shown to the player. The first, not
+# the last: `textbutton "OK" action Return()` and
+# `text "Hi" style "big"` both put the visible text first and configuration
+# after it.
+_UI_KEYWORDS = {"text", "textbutton", "tooltip", "caption", "alt", "label"}
+
+# Prefix words allowed in front of a say statement's dialogue, beyond the
+# speaker's own name and image attributes.
+_SAY_PREFIX_WORDS = {"extend", "nvl"}
+
+_IDENT_RE = re.compile(r"^[A-Za-z_][A-Za-z_0-9.]*$")
+_FIRST_WORD_RE = re.compile(r"^([A-Za-z_][A-Za-z_0-9]*)")
+
+
+@dataclass
+class Literal:
+    """One string literal, located exactly in the file."""
+
+    start: int          # offset of the first character inside the quotes
+    end: int            # offset just past the last character inside the quotes
+    quote: str          # the quote character, for re-escaping
+    triple: bool
+    line: int           # 0-based index of the line the literal opens on
+    depth: int          # bracket nesting at the opening quote
+
+
+@dataclass
+class Found:
+    """A translatable string plus where to write its translation back."""
+
+    text: str
+    start: int
+    end: int
+    quote: str
+    kind: str           # dialogue | menu | ui
+    line: int
+
+
+def scan_literals(source: str) -> tuple[list[Literal], list[str]]:
+    """Locate every string literal, and build the blanked-out code view.
+
+    Returns the literals and one "code line" per source line: the same text
+    with string contents and comments replaced by spaces, so positions still
+    line up with the original but no statement rule can be fooled by them.
+    """
+    literals: list[Literal] = []
+    code = list(source)
+    # A byte-order mark is not whitespace, so it would glue itself to the
+    # first statement's keyword and make line 1 unrecognisable. Blanking it in
+    # the code view fixes the classification while leaving the real offsets -
+    # and the mark itself - untouched.
+    if code and code[0] == "":
+        code[0] = " "
+    line_index = 0
+    depth = 0
+    index = 0
+    length = len(source)
+
+    while index < length:
+        char = source[index]
+
+        if char == "\n":
+            line_index += 1
+            index += 1
+            continue
+
+        if char == "#":
+            # Comment: blank to end of line. Ren'Py has no block comments.
+            while index < length and source[index] != "\n":
+                code[index] = " "
+                index += 1
+            continue
+
+        if char in "([{":
+            depth += 1
+            index += 1
+            continue
+        if char in ")]}":
+            depth = max(0, depth - 1)
+            index += 1
+            continue
+
+        if char not in "\"'":
+            index += 1
+            continue
+
+        # A string opens here. Triple quotes first, so `"""` is never read as
+        # an empty string followed by a stray quote.
+        quote = char
+        triple = source.startswith(quote * 3, index)
+        marker = quote * 3 if triple else quote
+        open_line = line_index
+        inner_start = index + len(marker)
+
+        cursor = inner_start
+        closed = False
+        while cursor < length:
+            current = source[cursor]
+            if current == "\\":
+                # Skip the escaped character so an escaped quote cannot close
+                # the string. Newlines inside the escape still count for
+                # line numbering.
+                if cursor + 1 < length:
+                    if source[cursor + 1] == "\n":
+                        line_index += 1
+                    cursor += 2
+                    continue
+                cursor += 1
+                continue
+            if current == "\n":
+                line_index += 1
+                if not triple:
+                    # An unterminated single-quoted string: treat the line end
+                    # as the end rather than swallowing the rest of the file.
+                    break
+                cursor += 1
+                continue
+            if source.startswith(marker, cursor):
+                closed = True
+                break
+            cursor += 1
+
+        inner_end = cursor
+        for position in range(inner_start, min(inner_end, length)):
+            if code[position] != "\n":
+                code[position] = " "
+
+        if closed:
+            literals.append(
+                Literal(
+                    start=inner_start,
+                    end=inner_end,
+                    quote=quote,
+                    triple=triple,
+                    line=open_line,
+                    depth=depth,
+                )
+            )
+            index = inner_end + len(marker)
+        else:
+            index = inner_end
+
+    code_lines = "".join(code).split("\n")
+    return literals, code_lines
+
+
+def _prefix_is_speaker(prefix: str) -> bool:
+    """True when the text before a say statement's dialogue is just a speaker.
+
+    A say statement's prefix is the character variable plus any image
+    attributes - all bare words. Anything with an operator or a call in it is
+    some other statement that happens to contain a string.
+    """
+    if not prefix:
+        return True
+    for word in prefix.split():
+        if word in _SAY_PREFIX_WORDS:
+            continue
+        if not _IDENT_RE.match(word):
+            return False
+    return True
+
+
+def _line_bounds(source: str) -> list[int]:
+    """Start offset of every line, so a line index can address the file."""
+    starts = [0]
+    for index, char in enumerate(source):
+        if char == "\n":
+            starts.append(index + 1)
+    return starts
+
+
+def find_translatable(source: str) -> list[Found]:
+    """Return every translatable string in one .rpy file."""
+    literals, code_lines = scan_literals(source)
+    line_starts = _line_bounds(source)
+
+    by_line: dict[int, list[Literal]] = {}
+    for literal in literals:
+        by_line.setdefault(literal.line, []).append(literal)
+
+    found: list[Found] = []
+    skip_indent: int | None = None
+    menu_indent: int | None = None
+    continuation = False
+    depth = 0
+
+    for index, code_line in enumerate(code_lines):
+        stripped = code_line.strip()
+        line_depth_before = depth
+        depth += sum(code_line.count(c) for c in "([{")
+        depth -= sum(code_line.count(c) for c in ")]}")
+        depth = max(0, depth)
+
+        was_continuation = continuation
+        # A statement continues onto the next line while brackets are open or
+        # the line ends in a backslash.
+        continuation = depth > 0 or code_line.rstrip().endswith("\\")
+
+        if not stripped:
+            continue
+
+        indent = len(code_line) - len(code_line.lstrip())
+
+        # A continuation line is part of the statement above it, not a
+        # statement of its own - classifying it would read `"Eileen")` from a
+        # multi-line Character() call as narration.
+        if was_continuation or line_depth_before > 0:
+            continue
+
+        if skip_indent is not None:
+            if indent > skip_indent:
+                continue
+            skip_indent = None
+
+        if menu_indent is not None and indent <= menu_indent:
+            menu_indent = None
+
+        if stripped.startswith("$"):
+            continue
+
+        match = _FIRST_WORD_RE.match(stripped)
+        first = match.group(1) if match else ""
+
+        if first in _BLOCK_SKIP:
+            skip_indent = indent
+            continue
+
+        if first == "menu":
+            menu_indent = indent
+            continue
+
+        if first == "screen":
+            # Screens hold player-visible text, so only the header is skipped.
+            continue
+
+        candidates = [lit for lit in by_line.get(index, []) if lit.depth == 0]
+        if not candidates:
+            continue
+
+        # `label` is two different statements: `label start:` is a script
+        # label, `label "Text"` inside a screen is a caption.
+        if first == "label" and not stripped[len("label"):].lstrip().startswith(
+            ("'", '"')
+        ):
+            continue
+
+        if first in _UI_KEYWORDS:
+            chosen = candidates[0]
+            kind = "ui"
+        elif first in _LINE_SKIP:
+            continue
+        else:
+            # Everything before the opening quote of the first string. The
+            # quote itself is excluded - it is not part of the speaker.
+            opening = candidates[0].start - (3 if candidates[0].triple else 1)
+            prefix = code_line[: opening - line_starts[index]].strip()
+            # An assignment that escaped the `$` and define checks is not
+            # dialogue, whatever it looks like.
+            if "=" in prefix:
+                continue
+            if not _prefix_is_speaker(prefix):
+                continue
+            # With two strings and no prefix the line is `"Speaker" "text"`,
+            # so the dialogue is the last one either way.
+            chosen = candidates[-1]
+            kind = "menu" if menu_indent is not None and not prefix else "dialogue"
+
+        raw = source[chosen.start : chosen.end]
+        try:
+            value = unescape(raw)
+        except EscapeError:
+            # An escape this tool will not round-trip. Leaving the line in the
+            # source untranslated is always recoverable; writing back a guess
+            # is not.
+            continue
+        if not value.strip() or not is_translatable(value):
+            continue
+        if chosen.triple:
+            # Triple-quoted bodies are found and skipped rather than
+            # translated: their content is re-indented by Ren'Py and a
+            # rewritten body would change the layout it depends on.
+            continue
+
+        found.append(
+            Found(
+                text=value,
+                start=chosen.start,
+                end=chosen.end,
+                quote=chosen.quote,
+                kind=kind,
+                line=index + 1,
+            )
+        )
+
+    return found

app/renpy/store.py

@@ -0,0 +1,260 @@
+"""On-disk state for uploaded Ren'Py projects.
+
+Kept apart from the RPG Maker projects in its own folder so neither engine can
+ever read the other's metadata, and so listing one never has to filter out the
+other.
+
+Only scripts are ever unpacked. People upload whole `game/` folders that are
+mostly art and audio, and none of it is read, so writing gigabytes to disk to
+translate a few megabytes of text would be pure cost.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import time
+import uuid
+import zipfile
+from dataclasses import asdict
+from pathlib import Path
+
+from .. import config
+from .extract import SCRIPT_SUFFIXES, Slot, Unit, extract, has_scripts, is_skipped
+
+STATUS_READY = "ready"
+STATUS_TRANSLATING = "translating"
+STATUS_DONE = "done"
+STATUS_FAILED = "failed"
+STATUS_CANCELLED = "cancelled"
+
+KIND = "renpy"
+
+
+def root() -> Path:
+    path = Path(config.PROJECT_DIR) / "renpy"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def project_dir(project_id: str) -> Path:
+    return root() / project_id
+
+
+def _meta_path(project_id: str) -> Path:
+    return project_dir(project_id) / "meta.json"
+
+
+def load_meta(project_id: str) -> dict | None:
+    try:
+        return json.loads(_meta_path(project_id).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def save_meta(project_id: str, meta: dict) -> None:
+    meta["updated_at"] = time.time()
+    path = _meta_path(project_id)
+    temp = path.with_suffix(".json.tmp")
+    temp.write_text(json.dumps(meta, ensure_ascii=False), encoding="utf-8")
+    temp.replace(path)
+
+
+def load_units(project_id: str) -> list[Unit]:
+    raw = json.loads((project_dir(project_id) / "units.json").read_text(encoding="utf-8"))
+    return [
+        Unit(
+            source=item["source"],
+            slots=[Slot(**slot) for slot in item["slots"]],
+        )
+        for item in raw
+    ]
+
+
+def save_units(project_id: str, units: list[Unit]) -> None:
+    (project_dir(project_id) / "units.json").write_text(
+        json.dumps([asdict(u) for u in units], ensure_ascii=False), encoding="utf-8"
+    )
+
+
+def load_translations(project_id: str) -> dict[str, str]:
+    path = project_dir(project_id) / "translations.json"
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def save_translations(project_id: str, translations: dict[str, str]) -> None:
+    path = project_dir(project_id) / "translations.json"
+    temp = path.with_suffix(".json.tmp")
+    temp.write_text(json.dumps(translations, ensure_ascii=False), encoding="utf-8")
+    temp.replace(path)
+
+
+def source_dir(project_id: str) -> Path:
+    return project_dir(project_id) / "source"
+
+
+class UploadError(ValueError):
+    """Raised for uploads that hold no usable Ren'Py script."""
+
+
+def _unpack_scripts(archive: Path, target: Path) -> int:
+    """Extract only the scripts from `archive`. Returns how many were written."""
+    written = 0
+    with zipfile.ZipFile(archive) as zf:
+        for member in zf.infolist():
+            if member.is_dir():
+                continue
+            name = Path(member.filename)
+            if name.suffix.lower() not in SCRIPT_SUFFIXES:
+                continue
+            if is_skipped(name):
+                continue
+
+            destination = (target / member.filename).resolve()
+            # Reject absolute paths and ../ escapes rather than trusting the
+            # archive to stay inside its own folder.
+            if not str(destination).startswith(str(target.resolve())):
+                raise UploadError(f"Unsafe path in zip: {member.filename}")
+
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            with zf.open(member) as incoming, open(destination, "wb") as outgoing:
+                shutil.copyfileobj(incoming, outgoing)
+            written += 1
+    return written
+
+
+def create(archive: Path, name: str) -> dict:
+    """Unpack an upload's scripts and index the text in them."""
+    project_id = uuid.uuid4().hex[:12]
+    base = project_dir(project_id)
+    source = source_dir(project_id)
+    source.mkdir(parents=True, exist_ok=True)
+
+    try:
+        count = _unpack_scripts(archive, source)
+    except zipfile.BadZipFile as exc:
+        shutil.rmtree(base, ignore_errors=True)
+        raise UploadError("Not a valid .zip file") from exc
+    except UploadError:
+        shutil.rmtree(base, ignore_errors=True)
+        raise
+
+    if not count or not has_scripts(source):
+        shutil.rmtree(base, ignore_errors=True)
+        raise UploadError(
+            "No Ren'Py scripts found in the zip. Expected .rpy or .rpyc files - "
+            "either on their own or inside a game folder."
+        )
+
+    units, broken = extract(source)
+
+    files: dict[str, dict] = {}
+    compiled = 0
+    for unit in units:
+        for slot in unit.slots:
+            entry = files.setdefault(slot.file, {"total": 0, "done": 0})
+            entry["total"] += 1
+            if not slot.writable:
+                compiled += 1
+
+    meta = {
+        "id": project_id,
+        "kind": KIND,
+        "name": name,
+        "engine": "renpy",
+        "status": STATUS_READY,
+        "created_at": time.time(),
+        "updated_at": time.time(),
+        "target_lang": None,
+        "total_units": len(units),
+        "total_slots": sum(f["total"] for f in files.values()),
+        "translated_units": 0,
+        "failed_units": 0,
+        "script_files": count,
+        # Strings that came out of compiled scripts. They cannot be written
+        # back into the .rpyc, so they travel in a generated translation file.
+        "compiled_slots": compiled,
+        "unreadable_files": broken,
+        "files": files,
+        "error": None,
+    }
+    save_units(project_id, units)
+    save_translations(project_id, {})
+    save_meta(project_id, meta)
+    return meta
+
+
+def list_projects() -> list[dict]:
+    metas = []
+    for child in root().iterdir():
+        if child.is_dir():
+            meta = load_meta(child.name)
+            if meta:
+                metas.append(meta)
+    return sorted(metas, key=lambda m: m.get("created_at", 0), reverse=True)
+
+
+def delete(project_id: str) -> bool:
+    target = project_dir(project_id)
+    if not target.is_dir():
+        return False
+    shutil.rmtree(target, ignore_errors=True)
+    return True
+
+
+def purge_expired() -> list[str]:
+    cutoff = time.time() - config.PROJECT_RETENTION_HOURS * 3600
+    removed = []
+    for meta in list_projects():
+        if meta.get("updated_at", 0) < cutoff:
+            if delete(meta["id"]):
+                removed.append(meta["id"])
+    return removed
+
+
+def build_output(project_id: str, meta: dict) -> Path:
+    """Package the translated scripts.
+
+    Only files that actually changed go in the zip. A Ren'Py game folder is
+    mostly art and audio, and shipping it back unchanged would turn a few
+    hundred kilobytes of script into a download the size of the game.
+    """
+    from . import inject, tl
+
+    base = project_dir(project_id)
+    staging = base / "build"
+    shutil.rmtree(staging, ignore_errors=True)
+    shutil.copytree(source_dir(project_id), staging)
+
+    units = load_units(project_id)
+    translations = load_translations(project_id)
+    lang = meta.get("target_lang") or "translated"
+
+    inject.apply(staging, units, translations)
+
+    # Files that received at least one translation - the only ones worth
+    # sending back.
+    changed = {
+        slot.file
+        for unit in units
+        if unit.source in translations
+        for slot in unit.slots
+        if slot.writable
+    }
+
+    generated = tl.write_runtime_translation(staging, units, translations, lang)
+
+    output = base / "translated.zip"
+    output.unlink(missing_ok=True)
+    with zipfile.ZipFile(output, "w", zipfile.ZIP_DEFLATED) as zf:
+        for name in sorted(changed):
+            path = staging / name
+            if path.is_file():
+                zf.write(path, name)
+        for path in generated:
+            zf.write(path, path.relative_to(staging).as_posix())
+    shutil.rmtree(staging, ignore_errors=True)
+    return output

app/renpy/text.py

@@ -0,0 +1,120 @@
+"""Ren'Py string-literal handling.
+
+Two jobs, both of which have to be exactly reversible or the game stops
+compiling:
+
+1. Turning the characters between the quotes in a .rpy file into the text a
+   translator should see, and back again.
+2. Deciding whether a string carries any language at all, so pure markup like
+   "{i}[player]{/i}" never costs a generation.
+
+Ren'Py's own text syntax matters here. `{...}` is a text tag, `[...]` is a
+variable interpolation, and both are doubled (`{{`, `[[`) to mean a literal
+brace or bracket. Those doubles must survive untouched: turning `[[` into `[`
+would change what the player sees, and turning it into a variable reference
+would crash the game on a missing name.
+"""
+
+from __future__ import annotations
+
+import re
+
+# The escape sequences this module round-trips. Deliberately short: every
+# sequence here is unescaped on the way in and re-escaped identically on the
+# way out, so a string that is never translated comes back byte-for-byte.
+#
+# A string containing any *other* backslash escape (Ren'Py's `\ ` hard space is
+# the one that shows up in practice) is refused by `unescape` rather than
+# guessed at - see `is_safe_literal`. Those strings are left in the source
+# untranslated, which costs a line of dialogue but can never corrupt a script.
+_UNESCAPE = {
+    "\\": "\\",
+    '"': '"',
+    "'": "'",
+    "n": "\n",
+    "t": "\t",
+}
+_ESCAPE = {
+    "\\": "\\\\",
+    "\n": "\\n",
+    "\t": "\\t",
+}
+
+_ESCAPE_RE = re.compile(r"\\(.)", re.DOTALL)
+
+# Text tags and interpolations, with the doubled literal forms matched first so
+# `{{` is never mistaken for the start of a tag.
+_MARKUP_RE = re.compile(
+    r"\{\{|\[\[|\{[^{}]*\}|\[[^\[\]]*\]"
+)
+
+
+class EscapeError(ValueError):
+    """Raised for a literal using an escape this module will not round-trip."""
+
+
+def is_safe_literal(raw: str) -> bool:
+    """True when `raw` (the characters between the quotes) round-trips."""
+    try:
+        unescape(raw)
+    except EscapeError:
+        return False
+    return True
+
+
+def unescape(raw: str) -> str:
+    """Turn the source characters between quotes into the readable text.
+
+    Raises EscapeError on an escape sequence outside the supported set, so the
+    caller can leave that literal alone instead of writing back something that
+    means something different.
+    """
+    out: list[str] = []
+    index = 0
+    length = len(raw)
+    while index < length:
+        char = raw[index]
+        if char != "\\":
+            out.append(char)
+            index += 1
+            continue
+        if index + 1 >= length:
+            raise EscapeError("literal ends on a lone backslash")
+        nxt = raw[index + 1]
+        if nxt not in _UNESCAPE:
+            raise EscapeError(f"unsupported escape \\{nxt}")
+        out.append(_UNESCAPE[nxt])
+        index += 2
+    return "".join(out)
+
+
+def escape(text: str, quote: str) -> str:
+    """Render `text` back into the characters that belong between `quote`s.
+
+    Only the enclosing quote is escaped: a single quote inside a double-quoted
+    string is left bare, exactly as Ren'Py writes it.
+    """
+    out: list[str] = []
+    for char in text:
+        if char in _ESCAPE:
+            out.append(_ESCAPE[char])
+        elif char == quote:
+            out.append("\\" + char)
+        else:
+            out.append(char)
+    return "".join(out)
+
+
+def strip_markup(text: str) -> str:
+    """Remove text tags and interpolations, keeping the words between them."""
+    return _MARKUP_RE.sub(" ", text)
+
+
+def is_translatable(text: str) -> bool:
+    """False for strings that are only markup, numbers or punctuation.
+
+    A screen is full of these - "{i}{/i}", "[points]", "- - -" - and each one
+    sent to the model costs a full generation and invites it to invent words
+    that were never in the source.
+    """
+    return any(char.isalpha() for char in strip_markup(text))

app/renpy/tl.py

@@ -0,0 +1,167 @@
+"""Deliver translations for text that lives in compiled scripts.
+
+A .rpyc cannot be edited: its syntax tree encodes the positions the engine
+checks against, so text has to reach the player another way. Ren'Py provides
+two, and a game that ships only .rpyc files needs both:
+
+  config.say_menu_text_filter   every line of dialogue and every menu choice
+                                passes through it before it is shown, keyed by
+                                the untranslated text
+  translate <lang> strings:     the interface strings the game marks with _()
+
+Nothing here runs unless the upload actually contained a compiled script. A
+project with its .rpy sources gets its text written straight into those files
+and needs no runtime hook at all.
+
+Two failure modes are designed out rather than tested for:
+
+* Ren'Py 7.5 and later refuse to start if the same `old` string appears twice
+  in a `translate strings:` block ("has been translated more than once"). The
+  entries are keyed by source text and asserted unique before writing.
+* A generated .rpy with a syntax error takes the whole game down on launch, so
+  the Python half of the hook is compiled here before it is written.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ..translation import LANGUAGES
+from .text import escape
+
+_JSON_NAME = "hymt_dialogue.json"
+_HOOK_NAME = "hymt_translate.rpy"
+_STRINGS_NAME = "hymt_strings.rpy"
+
+# The Python that goes inside the hook's `init python:` block, kept here as
+# plain source so it can be compiled before it is written into a .rpy.
+_HOOK_BODY = '''\
+import json
+import os
+
+def _hymt_load():
+    path = os.path.join(config.gamedir, "tl", "__LANG__", "__JSON__")
+    try:
+        with open(path, "rb") as handle:
+            return json.loads(handle.read().decode("utf-8"))
+    except Exception:
+        return {}
+
+_hymt_map = _hymt_load()
+_hymt_previous = getattr(config, "say_menu_text_filter", None)
+
+def _hymt_filter(text):
+    if _hymt_previous is not None:
+        text = _hymt_previous(text)
+    return _hymt_map.get(text, text)
+
+config.say_menu_text_filter = _hymt_filter
+'''
+
+
+def language_name(target_lang: str) -> str:
+    """Map a language code to the directory name Ren'Py uses.
+
+    Ren'Py keys translations by an English language name in lower case
+    ("turkish"), not by an ISO code, and the tl/ folder has to match.
+    """
+    code = (target_lang or "").strip().lower()
+    name = LANGUAGES.get(code, code)
+    return name.lower().replace(" ", "") or "translated"
+
+
+def _render_hook(lang: str) -> str:
+    body = _HOOK_BODY.replace("__LANG__", lang).replace("__JSON__", _JSON_NAME)
+    # Fail here, in the generator, rather than in the player's game.
+    compile(body, "<hymt hook>", "exec")
+
+    indented = "\n".join(
+        ("    " + line) if line.strip() else "" for line in body.splitlines()
+    )
+    return (
+        "# Generated translation hook.\n"
+        "#\n"
+        "# The dialogue in this game is inside compiled .rpyc scripts, which\n"
+        "# cannot be edited. This filter swaps each line for its translation\n"
+        "# as the game displays it, and leaves anything untranslated alone.\n"
+        "\n"
+        "init python:\n" + indented + "\n"
+    )
+
+
+def _render_strings(lang: str, pairs: list[tuple[str, str]]) -> str:
+    lines = [
+        "# Generated interface translations.",
+        "",
+        f"translate {lang} strings:",
+        "",
+    ]
+    for source, translated in pairs:
+        lines.append(f'    old "{escape(source, chr(34))}"')
+        lines.append(f'    new "{escape(translated, chr(34))}"')
+        lines.append("")
+    return "\n".join(lines)
+
+
+def game_root(staging: Path, units: list) -> Path:
+    """The directory the generated files belong in.
+
+    Ren'Py resolves `config.gamedir` to the game's `game/` folder, and that is
+    where tl/ has to live. Uploads arrive either as a game folder or as a bare
+    pile of scripts, so the folder is found from where the scripts actually
+    sit rather than assumed - putting the hook beside `game/` instead of
+    inside it would leave the two halves of the output extracting to different
+    places.
+    """
+    for unit in units:
+        for slot in unit.slots:
+            parts = Path(slot.file).parts
+            if "game" in parts:
+                return staging.joinpath(*parts[: parts.index("game") + 1])
+    return staging
+
+
+def write_runtime_translation(
+    staging: Path,
+    units: list,
+    translations: dict[str, str],
+    target_lang: str,
+) -> list[Path]:
+    """Write the hook, its data file and the strings block into `staging`.
+
+    Returns the files created, which is empty when the project had no compiled
+    scripts.
+    """
+    mapping: dict[str, str] = {}
+    for unit in units:
+        translated = translations.get(unit.source)
+        if translated is None or translated == unit.source:
+            continue
+        if any(not slot.writable for slot in unit.slots):
+            mapping[unit.source] = translated
+
+    if not mapping:
+        return []
+
+    lang = language_name(target_lang)
+    root = game_root(staging, units)
+    tl_dir = root / "tl" / lang
+    tl_dir.mkdir(parents=True, exist_ok=True)
+
+    json_path = tl_dir / _JSON_NAME
+    json_path.write_text(
+        json.dumps(mapping, ensure_ascii=False, indent=1), encoding="utf-8"
+    )
+
+    hook_path = root / _HOOK_NAME
+    hook_path.write_text(_render_hook(lang), encoding="utf-8")
+
+    # dict keys are unique by construction, so no `old` can repeat - the
+    # condition Ren'Py refuses to start on.
+    pairs = sorted(mapping.items())
+    assert len({source for source, _ in pairs}) == len(pairs)
+    strings_path = tl_dir / _STRINGS_NAME
+    strings_path.write_text(_render_strings(lang, pairs), encoding="utf-8")
+
+    return [json_path, hook_path, strings_path]