Localization factory

1nika: v12workflow:3  id: localization-factory4  description: "glob docs → parallel read → parallel translate → mirror tree"5​6model: ollama/qwen3.5:4b   # local default · swap for mistral/mistral-large (EU model for EU locales)7​8const:9  lang: "fr"10  # The committed rehearsal tree. Point this at ./docs (or wherever yours11  # lives) and change `permits.fs.read` to match, in the same edit.12  source_root: "./examples/fixtures/docs"13​14⛨permits:15  ⛨tools: ["nika:glob", "nika:jq", "nika:read", "nika:write"]16  ⛨fs:17    # `nika:glob` opens the ROOT of its pattern, so the bound has to cover18    # the directory AND everything under it — `**` does both (it matches the19    # dir itself and any descendant at any depth). A bound naming only the20    # `.md` files refuses the glob before it lists anything:21    # `NIKA-SEC-004 · ./examples/…/docs resolves outside permits.fs.read`.22    ⛨read: ["./examples/fixtures/docs/**"]23    # The mirror is as deep as the source tree, so this one earns its `**`:24    # every locale lands under ./i18n/ and nothing lands outside it. Naming25    # the locale (`./i18n/fr/**`) would be tighter but would have to be26    # re-edited for every value of `const.lang` — the bound is the tree the27    # factory owns.28    ⛨write: ["./i18n/**"]29​30tasks:31  # ── the collection is discovered, never declared ────────────────────32  files:33    ◆invoke:34      tool: "nika:glob"35      args:36        pattern: "${{ const.source_root }}/**/*.md"37        exclude: ["**/node_modules/**"]38​39  # ── stage 1 · read every file, 8 at a time ─────────────────────────40  texts:41    with:42      files: ${{ tasks.files.output }}43    for_each: ${{ with.files }}44    max_parallel: 8                    # local disk · the only cost is file handles45    ◆invoke:46      tool: "nika:read"47      args: { path: "${{ item }}" }48​49  # ── the zip · path + text, and the source root comes off ───────────50  # `texts` is an array in the SAME ORDER as `files`, so transpose pairs51  # them index-for-index. `ltrimstr` makes each path relative to the source52  # root — that stripped path is what the mirror tree is built from.53  pairs:54    with:55      files: ${{ tasks.files.output }}56      texts: ${{ tasks.texts.output }}57    ◆invoke:58      tool: "nika:jq"59      args:60        input: ["${{ with.files }}", "${{ with.texts }}"]61        expression: >-62          transpose63          | map({ path: (.[0] | ltrimstr("${{ const.source_root }}/")), text: .[1] })64​65  # ── stage 2 · translate every file, 3 at a time ────────────────────66  translated:67    with:68      pairs: ${{ tasks.pairs.output }}69    for_each: ${{ with.pairs }}70    max_parallel: 3                    # rate-limit the provider, not the disk71    fail_fast: false                   # finish the batch · one bad file is not a batch failure72    on_error:73      recover: null                    # null holds the index open so the zip below stays aligned74    ◇infer:75      max_tokens: 4000                 # a doc page, not a book · the cost ceiling is a real number76      prompt: |77        Translate to ${{ const.lang }} · keep the markdown structure, leave78        code blocks untouched, and keep the original tone ·79        ${{ item.text }}80​81  # ── the fan-in · drop the files that failed, keep their paths ──────82  # Second transpose, same law: `translated` is index-aligned with `pairs`83  # because `recover: null` filled the failures in place. `select(.[1] !=84  # null)` is where a failed translation leaves the batch — by VALUE, after85  # the fact, not by aborting the fan-out.86  bundle:87    with:88      pairs: ${{ tasks.pairs.output }}89      translated: ${{ tasks.translated.output }}90    ◆invoke:91      tool: "nika:jq"92      args:93        input: ["${{ with.pairs }}", "${{ with.translated }}"]94        expression: >-95          transpose96          | map(select(.[1] != null))97          | map({ path: .[0].path, text: .[1] })98​99  # ── stage 3 · write the mirror ─────────────────────────────────────100  mirror:101    with:102      bundle: ${{ tasks.bundle.output }}103    for_each: ${{ with.bundle }}104    max_parallel: 8105    ◆invoke:106      tool: "nika:write"107      args:108        path: "./i18n/${{ const.lang }}/${{ item.path }}"109        content: "${{ item.text }}"110        create_dirs: true              # the mirror's subdirectories do not exist yet111​112outputs:113  translated:114    value: ${{ tasks.bundle.output }}115    description: "Every file that made it through, as {path, text} · the mirror's manifest"116​