AcTePuKc/bg-game-translation-qa

Bulgarian Game Localization QA

Use this skill for Bulgarian game localization work where preserving the file format is as important as improving the text. Make minimal, safe changes and prefer focused patches over rewriting whole files unless the user explicitly asks for a full rewrite.

Core Workflow

1. Identify the file format and the translatable fields before editing.
2. Preserve all structure, ordering, delimiters, quoting, escaping, comments, keys, IDs, and metadata.
3. Translate or edit only user-facing text.
4. Preserve placeholders, formatting tags, variables, escape sequences, and line breaks exactly unless the user explicitly asks to change them.
5. Follow any project glossary, termbase, style guide, or existing translation memory provided by the user or present in the project.
6. Report uncertain strings separately instead of silently guessing.
7. Summarize what changed, what was left unchanged, and any risks or questions.

Non-Translatable Content

Do not translate or normalize internal identifiers, enum names, filenames, file paths, class names, function names, object names, asset names, event names, console commands, config keys, IDs, or technical metadata unless the user explicitly marks them as player-facing text.

For structured files, keep row counts, key order, nesting, separators, and encoding intact. For CSV/TSV tables, preserve the exact column structure. For JSON/XML/INI/PO-style files, preserve syntax and escaping.

Placeholders and Tags

Preserve placeholders and formatting tags byte-for-byte, including case, punctuation, nesting, spacing, and order. Do not translate text inside variables unless it is clearly player-facing display text.

Always protect patterns such as:

• {PLAYER}
• {0}
• %s
• %d
• <color=...>
• </color>
• <b>
• </b>
• \n
• \t
• [br]
• [[...]]
• $VARIABLE
• ${variable}

Read references/placeholders.md when the task includes unfamiliar tokens, rich text, UI markup, scripting syntax, or format-specific placeholders.

Bulgarian Localization Style

Use natural Bulgarian phrasing, not literal English word order. Keep UI text concise and readable, especially for buttons, menus, achievements, tooltips, and combat messages.

Prefer culturally appropriate Bulgarian translation over transliteration when possible, but keep established game terms and project glossary choices consistent. Preserve character voice in dialogue and avoid over-formalizing casual or humorous speech.

When speaker or player gender is unknown, avoid forced gendered phrasing where Bulgarian allows a neutral construction. Do not introduce Russian- or Ukrainian-sounding phrasing. Avoid unnecessary capitalization copied from English headings, item names, or UI labels unless the project style requires it.

Technical Terms and Borrowings

Do not translate a technical term mechanically just because it is visible in the source. First determine whether it is an internal identifier, an established specialist term, or player-facing prose.

• Keep API names, commands, config keys, class names, and other identifiers unchanged.
• For player-facing text, prefer a natural Bulgarian description of the function over a literal borrowing.
• If the source does not establish the technical role precisely, do not invent one. Use a neutral functional phrase or report the string as uncertain.
• Follow the project glossary when it defines a term, even when another Bulgarian option is also possible.

Examples:

Source term	Player-facing text	Technical explanation	Do not assume
hook	механизъм / точка за включване	обработчик / точка за разширяване	that it means a module or „кука“
compatibility hook	механизъм за съвместимост	обработчик за съвместимост or точка за включване за съвместимост	that модул, кука, or прихващач is always correct
fix	поправка / корекция	поправка за съвместимост	that slang фикс fits the audience
handler	describe its action if needed	обработчик	that it should be transliterated as хендлър

For example, translate The journal level label was corrected through the compatibility hook. as Надписът за нивото в дневника е коригиран чрез механизма за съвместимост. for a player-facing changelog. Do not use кука за съвместимост by default.

Repeated Game Terms

When a game mechanic or UI concept repeats, decide its Bulgarian name at the first clear occurrence and record it in the project glossary. Do not collapse related terms into one Bulgarian word merely because they sound similar in English.

Source terms to distinguish	Possible Bulgarian choices	QA risk
skill, ability, perk, trait, feat	умение, способност, привилегия, черта	different progression systems become indistinguishable
buff, debuff, status effect	положителен ефект, отрицателен ефект, ефект на състояние	player cannot tell a bonus from a condition
cooldown, charge, stack	време за изчакване, заряд, натрупване	timing, resource, and accumulation mechanics are conflated
loot, drop	плячка, изпуснат предмет	a reward pool is confused with an item produced by an event or enemy
spawn, despawn, trigger	появяване, изчезване, задействане	world events and interaction conditions become vague
crafting, recipe, blueprint, upgrade	изработка, рецепта, чертеж, подобрение	crafting, unlocks, and upgrades lose their mechanical distinction
save, load, save slot	запазване, зареждане, място за запазена игра	the action, the saved game, and its location are confused

Also review context-sensitive technical words such as support, state, patch, build, release, and slot. For example, support may mean съвместимост, поддръжка, or помощ; patch may be поправка, корекция, or обновление.

Address and Register

Do not default to formal Вие / -те phrasing for player-facing game UI, tutorials, prompts, objectives, or generic system messages. Prefer informal singular ти / -ш or a natural neutral construction unless the project glossary, character voice, setting, or source context clearly requires formal address.

Flag mismatched address/register as a QA issue, especially when English you was translated as formal Bulgarian without evidence that the game uses formal player address.

Examples:

• You have to do this. -> prefer Трябва да направиш това. or Това трябва да се направи. depending on context
• avoid defaulting to Вие трябва да направите това. in normal player-facing UI
• keep formal address for nobles, officials, customer-service-like UI, intentionally distant narration, or projects whose established style uses Вие

Translation Ballast

Flag source phrases that are technically translated but add unnecessary weight in Bulgarian UI text. Treat these as QA warnings for manual review, not automatic fixes.

Use severity low and action manual review for possible translation ballast. Keep the phrase when it carries real gameplay, spatial, targeting, timing, or mechanical information.

Common examples:

• through the air after verbs like shoot, fire, throw, or launch
  • shoots arrows through the air -> изстрелва стрели
  • flag overly literal variants like изстрелва стрели във въздуха unless air travel is mechanically relevant
• nearby when proximity is already implied by the Bulgarian sentence
  • when enemies are nearby -> когато има врагове наблизо
  • when senses lifeforms nearby -> когато усети живи същества наблизо
  • keep наблизо when it defines detection radius, targeting, trigger range, or location
• into pieces / apart after verbs that already imply breaking
  • smashing things apart -> разбиване на неща
  • avoid forced phrasing like разбиване на неща на парчета unless fragments/pieces matter
• on the ground, in front of you, with your hands, or by hand when the Bulgarian verb or context already implies the information
  • keep them when they carry real position, input, crafting, or interaction constraints

Read references/bg-text.md for practical Bulgarian style guidance and references/glossary-template.md when creating or extending a project glossary.

Relationship to bg-text

When the bg-text skill is available or the user asks to use it, use it as a companion reference for Bulgarian typography, clarity, punctuation, grammar, and general editorial quality. Apply this skill's game localization constraints first: never let typography or style cleanup alter protected structure, keys, IDs, placeholders, tags, escape sequences, line breaks, or project terminology.

For game files, treat bg-text as language-quality guidance, not permission to rewrite whole files or normalize engine-specific syntax.

QA Checklist

Before final output, check for:

• broken, changed, reordered, or missing placeholders
• missing, malformed, or unbalanced formatting tags
• changed keys, IDs, filenames, paths, or metadata
• missing rows or changed table shape
• duplicate IDs introduced or missed
• untranslated English in translated fields
• Ukrainian leftovers
• Russian leftovers
• inconsistent glossary terms
• technical terms translated mechanically or inconsistently
• related game mechanics collapsed into one term without a glossary decision
• overly literal Bulgarian
• mismatched formal/informal address, especially unnecessary Вие in player-facing UI
• possible translation ballast / literal phrase that should be manually reviewed
• UI text that is obviously too long for its likely control

Read references/qa-checklist.md for a practical final review pass.

Output Expectations

Prefer patch-style changes and focused corrections. Explain meaningful translation or QA changes briefly. List uncertain strings separately with the key/ID or location, the issue, and the safest suggested handling.

If the file is large, inspect enough surrounding context to avoid terminology drift, then edit only the requested scope. If a requested change would risk damaging structure or placeholders, stop and ask for clarification.