qudjp-localization-triage

QudJP Localization Triage

Overview

Use this skill to turn runtime untranslated text into the smallest correct QudJP localization change. Route text at the producer or owner when possible, use dictionary leaves only for fixed literals, and leave sink fallback as observability rather than the primary solution.

Workflow

1. Establish current evidence.

   • Read repo instructions first, including scoped AGENTS.md files for C# patches, localization assets, or scripts.
   • Use fresh ~/Library/Logs/Freehold Games/CavesOfQud/Player.log when the user asks about live gameplay output.
   • Treat Player.log as route evidence, not just an untranslated-string list. Use scripts/triage_untranslated.py or equivalent parsing to preserve sink, route, category, and producer context before assigning work.
   • Classify each finding as untranslated fixed literal, generated template, generated name, composed route, already-Japanese runtime noise, or intentional pass-through.
   • Group broad runtime surfaces by owner route or route family before deciding backlog scope. Do not collapse sink-adjacent families such as UITextSkinTranslationPatch, GetDisplayName*, Popup*, and generic message sinks into one undifferentiated "untranslated" bucket.
   • For active-effects UI or ability-bar effect text, do not treat one observed effect as the backlog. Inventory the producer family through Effect.DisplayName, Effect.GetDescription, Effect.GetDetails, GameObject.ShowActiveEffects, and ability-bar active-effect routes, then classify cooking, stance, tonic, disease, and other effect owners separately.
   • When an observed English source looks like a stable label but contains a domain noun, Title Case phrase, number, object name, mutation/effect name, date, festival, dish, faction, or village term, treat it as generated until the producer proves it is a fixed literal.
   • Treat semantically odd English collocations, noun piles, and fantasy/domain word salad as generated until proven otherwise, even when they are lowercase and look like ordinary noun phrases. Be especially suspicious of creature/material/object, body-part/material/object, place/faction/title, dish/ingredient, or sacred/profane noun piles such as tortoise keratin tent, dragonfly chitin tent, algal convalessence, sealed, or the Desiccated Spectre. Before adding dictionary coverage, trace the producer or data source and decide whether the fix is component reconstruction, scoped component leaves, an owner translator, or a proven fixed literal.
   • When the user's surface name is broad, such as chargen, inspect adjacent runtime probes that share the text family or UI route, then state which screens are primary and which are follow-up risk.
   • For broad C# localization coverage, static-analysis completion, or "where to start" mapping, pair with roslyn-static-analysis and start from docs/localization-coverage-map.json. Blueprint XML merge data is not a C# static-analysis surface.
   • Quote static queue counts, top files, or representative families only from current command output or a current generated artifact. The checked map plus queues can guide backlog scope, but map green alone does not close a runtime issue without owner-route evidence, tests, or fresh runtime proof.
   • When the user provides an issue sample, review comment, or remembered phrase without a matching fresh log row, treat the sample as a hypothesis for route tracing, not as proof of current runtime failure. Report the missing runtime evidence separately, then use decompiled producers, data sources, adjacent logs, tests, or existing route observability to decide the next verification step.
   • If the issue sample is already covered by current code or tests, do not propose a duplicate implementation. Report the existing owner-route coverage, identify the focused checks or runtime evidence still needed, and classify the remaining work as verification, regression-test gap, follow-up risk, or closeout.
   • If the requested text is absent from the current log, say it is absent in that log. Use adjacent logs/routes only as risk evidence, not proof that the requested text is still failing.
   • For TMP/UI rendering regressions, separate the owner/root refresh path from replacement or fallback recovery paths before declaring the issue fixed. Visible text alone is not enough: confirm the fresh Player.log has no QudJP exceptions or route-specific probe failures, and state whether any observed fallback log is an unrelated engine/font fallback or the UI fallback path under investigation.
   • Treat dictionary duplicate-key observations that do not change the selected translation as verbose diagnostics, not normal startup warnings. If they must remain observable, route them through RuntimeDiagnostics.LogVerboseProbe(...) so release Player.log stays focused on load counts and actionable failures.
   • When PR review comments are part of the request, pair this skill with github:gh-address-comments or post-pr-convergence; CodeRabbit/check pass alone is not enough if unresolved review threads may remain.
   • Treat an actionable review comment as a representative symptom for the whole route family, not only the exact line, branch, or literal named in the comment. Before editing, enumerate sibling owner tokens, parser branches, punctuation/casing variants, scoped dictionary homes, and owner-vs-sink boundaries that share the same contract, then use that family audit to choose focused edge tests.
   • When a generated pattern captures object, actor, target, faction, mutation, or item names that may already be localized, audit the grammar boundary after each capture for Japanese particles such as の, を, に, で, は, が, と, から, へ, and より. Do not treat an English possessive like 's/s' as the only localized-name boundary. Scope this audit to the same producer, message-frame family, route helper, or adjacent regex group that repeats the same capture contract, and check both source-regex boundaries and output templates that append particles after captured text.
   • When reading CodeRabbit state through GitHub GraphQL, compare headRefOid, check/status context, review decision, and the commit range named in recent review bodies from the PR reviews connection. Query reviews(first: N) or reviews(last: N) with pagination, and use the states argument when filtering for states such as APPROVED or CHANGES_REQUESTED; older review bodies may remain after force-pushes while the current CodeRabbit status context is already passing, and unresolved threads alone can also miss actionable current-head review-body notes.
   • When a current-head duplicate or review-body finding conflicts with the route code, first prove whether it is a false positive with the owning translator, route fixture, and focused tests. If the current implementation already translates the captured text, reply with exact owner-function and test evidence instead of deleting tokens, weakening route semantics, or adding sink-side masking.

2. Trace the source before choosing a fix.

   • Use rg for literal strings, symbol names, files, and quick dictionary searches.
   • Use just sg-cs '<pattern>' for decompiled C# producers when call shape, argument structure, wrappers, assignments, overloads, or attributes matter.
   • Use just sg-cs '<pattern>' Mods/QudJP/Assemblies/src to compare existing patch patterns in repo-owned C#.
   • When a decision depends on C# producer/sink ownership, do not stop at literal rg. Run at least one just sg-cs query that matches the relevant call shape, such as AddMyActivatedAbility($$$ARGS), ExpandString($$$ARGS), AddEntityListItem($$$ARGS), SetText($$$ARGS), or MessagePatternTranslator.Translate($$$ARGS). If rg is sufficient because the source is a plain data file or fixed asset literal, state that explicitly in the evidence summary.
   • For broad static C# backlog work, use just static-producer-owner-queue and just text-construction-surface-queue before ad hoc literal searches. If the user says "other scanner surfaces" without naming a scanner, start with the ui_text_construction lane; add scanner work only when the existing map/queue cannot express the needed classification.
   • For generated ability names, effect names, mutation labels, and similar UI labels, trace the method or object data that composes the visible name before adding any dictionary entry.
   • For UI fields named KeyDescription, hotkey, command, or similar, classify the value before translating it. Preserve input identifiers, control-binding descriptors, and key-only labels such as 7, 9, Ctrl+Tab, Accept, or CmdHelp; translate only the player-visible action label when the producer proves the field is not used as an input contract. Add a focused regression for both a translated label and an unchanged input descriptor when touching these routes.
   • For generated or composed text, record the route shape before choosing a fix: fixed frame with generated noun, generated name only, generated sentence from reusable grammar templates, or final sink-only display with no known owner route yet.
   • When a generated name appears inside a fixed message, popup, combat line, or other sentence frame, trace both owners separately: the outer frame producer/pattern and the captured name's producer. Translate the frame at its owner route, and translate the captured generated name through its owning display-name or component reconstruction route rather than by adding an exact phrase leaf.
   • When a route-local regex or parser decomposes a generated sentence into captures, audit every owner/source/kind/item/mutation/effect slot before concatenating the Japanese output. Reuse the route's existing exact or visible phrase translator for captured slots when possible, and keep the current fallback only for unknown slot values. A phrase already translated as a standalo

Content truncated.