Merge pull request #1 from Underslumber/fix/update-translation

Fix/update translation

.github/workflows/build.yml

@@ -0,0 +1,117 @@
+name: Build Mod Package
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: windows-latest
+
+    defaults:
+      run:
+        shell: pwsh
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Prepare workspace
+        run: |
+          $ErrorActionPreference = "Stop"
+
+          if (-not (Test-Path -LiteralPath "Mods\\DnD 5.5e AIO Russian\\Localization\\Russian\\russian.xml")) {
+              throw "Repository sources are not available in the runner workspace."
+          }
+
+          New-Item -ItemType Directory -Path ".tools\\lslib" -Force | Out-Null
+          New-Item -ItemType Directory -Path "build" -Force | Out-Null
+
+      - name: Resolve version tag
+        id: vars
+        run: |
+          $ErrorActionPreference = "Stop"
+          $versionTag = ""
+          if ($env:GITHUB_REF -like "refs/tags/v*") {
+              $versionTag = $env:GITHUB_REF_NAME
+          }
+          "version_tag=$versionTag" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+
+      - name: Download latest LSLib release
+        run: |
+          $ErrorActionPreference = "Stop"
+          $release = Invoke-RestMethod -Uri "https://api.github.com/repos/Norbyte/lslib/releases/latest"
+          $asset = $release.assets | Where-Object { $_.name -match '\.zip$' } | Select-Object -First 1
+
+          if (-not $asset) {
+              throw "Could not find a downloadable LSLib zip asset in the latest release."
+          }
+
+          Invoke-WebRequest -UseBasicParsing -Uri $asset.browser_download_url -OutFile ".tools/lslib/lslib.zip"
+          Expand-Archive -LiteralPath ".tools/lslib/lslib.zip" -DestinationPath ".tools/lslib" -Force
+
+      - name: Build .pak
+        run: |
+          $ErrorActionPreference = "Stop"
+          $divine = Get-ChildItem -Path ".tools\\lslib" -Recurse -File |
+            Where-Object { $_.Name -ieq "Divine.exe" } |
+            Select-Object -First 1
+
+          if (-not $divine) {
+              throw "Divine.exe was not found in the downloaded LSLib release."
+          }
+
+          & ".\\scripts\\build.ps1" -DivinePath $divine.FullName -Workspace "${{ github.workspace }}" -VersionTag "${{ steps.vars.outputs.version_tag }}"
+
+      - name: Show build result
+        run: |
+          $ErrorActionPreference = "Stop"
+          $archiveBaseName = "DnD 5.5e AIO Russian"
+          if ($env:GITHUB_REF -like "refs/tags/v*") {
+              $archiveBaseName = "DnD 5.5e AIO Russian $env:GITHUB_REF_NAME"
+          }
+          $zipPath = [System.IO.Path]::GetFullPath((Join-Path "${{ github.workspace }}" "build/$archiveBaseName.zip"))
+
+          Get-ChildItem "build/DnD 5.5e AIO Russian.pak", "build/info.json", $zipPath |
+            Select-Object FullName, Length, LastWriteTime
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: bg3-dnd55e-russian-localization-${{ github.run_number }}
+          path: build/*
+          if-no-files-found: error
+
+      - name: Create or update GitHub release
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          $ErrorActionPreference = "Stop"
+          $tagName = "${{ github.ref_name }}"
+          $zipPath = Join-Path $env:GITHUB_WORKSPACE "build\\DnD 5.5e AIO Russian $tagName.zip"
+
+          if (-not (Test-Path -LiteralPath $zipPath)) {
+              throw "Release archive was not found at '$zipPath'."
+          }
+
+          gh release view $tagName --repo "${{ github.repository }}" *> $null
+
+          if ($LASTEXITCODE -ne 0) {
+              gh release create $tagName $zipPath `
+                --repo "${{ github.repository }}" `
+                --title $tagName `
+                --notes ""
+          }
+          else {
+              gh release upload $tagName $zipPath `
+                --repo "${{ github.repository }}" `
+                --clobber
+          }

.gitignore

@@ -1,6 +1,7 @@
 build/
 build-stage*
 .tools/
+.cache/
 *.pak
 *.tmp
 *.temp

ACTIONS.md

@@ -1,6 +1,6 @@
 # ACTIONS.md
 
-VERSION: 2
+VERSION: 3
 MODE: machine-first
 LANG: ru
 
@@ -20,6 +20,7 @@ EXECUTION_BASELINE:
   - minimal_non_breaking_changes: true
   - steps_count_range: [3, 7]
   - before_commit_push: request_user_approval
+  - prefer_existing_repo_scripts_over_manual_work: true
 
 REPORT_FORMAT:
   - done
@@ -28,6 +29,48 @@ REPORT_FORMAT:
   - remaining
 
 ACTIONS:
+  translation:diff:
+    intent: fetch_upstream_english_and_compare_with_ru
+    inputs:
+      - AGENTS.md::Canonical Paths::Upstream English reference
+      - Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml
+    plan:
+      - run_scripts/get-upstream-english.ps1_and_wait_until_output_exists
+      - run_scripts/compare-translation.ps1_after_upstream_download_only
+      - classify_diff_into_missing_changed_stale
+      - write_machine_readable_and_markdown_reports_for_local_review
+    checks:
+      - xml_valid
+      - cache_path_gitignored
+      - local_only_no_ci_workflow_required
+      - translation_steps_not_parallelized_when_file_dependency_exists
+    outputs:
+      - .cache/upstream/english.xml
+      - build/translation-diff/summary.json
+      - build/translation-diff/summary.md
+      - build/translation-diff/candidates.json
+  translation:apply:
+    intent: apply_translation_edits_to_russian_xml
+    inputs:
+      - Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml
+      - build/translation-diff/candidates.json
+      - prepared_update_texts_for_updates_and_optional_adds
+    plan:
+      - create_temporary_copy_of_russian_xml
+      - load_candidate_edit_file_and_temporary_xml
+      - fail_if_add_entry_has_empty_text
+      - apply_updates_and_optional_new_entries_by_contentuid
+      - write_utf8_bom_xml_to_temporary_copy
+      - validate_temporary_xml_via_separate_script
+      - replace_original_russian_xml_after_successful_validation
+      - report_changed_entries
+    checks:
+      - xml_valid
+      - contentuid_uniqueness_preserved
+      - only_requested_entries_changed
+      - no_partial_replace_on_validation_failure
+    outputs:
+      - Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml
   translation:update:
     intent: sync_ru_translation_with_upstream
     inputs:
@@ -35,16 +78,22 @@ ACTIONS:
       - glossary/glossary.normalized.json
       - AGENTS.md::Canonical Paths::Upstream English reference
     plan:
-      - compare_en_vs_ru_by_keys
-      - classify_diff_into_new_changed_stale_candidate
-      - update_ru_for_new_and_changed_using_glossary
-      - validate_xml_structure_and_service_attributes
-      - prepare_delta_summary_counts
+      - run_translation:diff_sequentially
+      - if_summary_has_no_missing_no_version_mismatch_no_stale_report_translation_up_to_date_and_stop
+      - if_diff_exists_stop_after_generating_build/translation-diff/candidates.json_until_prepared_edits_are_provided_explicitly
+      - review_build/translation-diff/candidates.json_before_apply
+      - reuse_glossary_for_term_consistency_when_preparing_texts
+      - run_translation:apply_only_after_candidate_texts_are_filled_and_explicit_edits_path_is_passed
     checks:
       - xml_valid
       - glossary_consistency
       - scope_limited_to_localization_and_allowed_metadata
+      - no_upstream_download_compare_race_condition
     outputs:
+      - message: translation_up_to_date
+      - build/translation-diff/summary.json
+      - build/translation-diff/summary.md
+      - build/translation-diff/candidates.json
       - Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml
       - optional: Mods/DnD 5.5e AIO Russian/meta.lsx (release-only)
     after_success:

AGENTS.md

@@ -1,87 +1,228 @@
 # AGENTS.md
 
-## General Rules (MUST)
+## Execution Model (MUST)
+- Read this file first; treat as system-level constraints.
+- Priority:
+  1. User instructions
+  2. AGENTS.md
+  3. Existing code/style
+  4. Best practices
+- Prefer minimal, non-breaking changes.
+- Do not introduce unnecessary abstractions.
 
-### Git Collaboration Policy (General)
-- Commit/push only after explicit user approval.
-- After approval: commit and push immediately.
-- Branch switch prompt (`fix/*` or `feat/*`): ask once at dialogue start; reuse the explicit user decision for all subsequent fix/feature tasks in the same dialogue.
-- After finishing work in `fix/*` or `feat/*`: propose either
-  1. creating an MR into `main`, or
-  2. merging to `main` immediately and deleting the `fix/*`/`feat/*` branch.
-- If push fails: retry up to 2 more times with 3s pause.
-- Approval prompts for pending actions: short direct phrasing, no soft/opening phrases; response format is mandatory:
-  - binary action: yes/no question.
-  - multiple actions/combinations: numbered options only.
+---
 
-### Cleanup (General)
-- Do not leave temporary/debug artifacts in repo.
-- Remove additional debug/temp dirs unless user asked to keep them.
+## Communication (MUST)
+- Answer first, then request approval if needed.
+- Concise, meaningful, no filler.
+- Do not end response with only procedural choice.
 
-### Rules Maintenance (General)
-- For changes to rules files (`AGENTS.md`, `ACTIONS.md`): prefer optimized, compressed edits for AI-agent execution (machine-readable, unambiguous).
-- Keep rule updates minimal and non-duplicative: merge overlapping points, remove redundancy, preserve intent.
+Approval/clarification:
+- ask once, no repetition
+- binary → yes/no
+- multiple → numbered options + brief context
 
-## Project-Specific Rules (MUST)
+- File links in repo docs/checklists: relative paths, `/`, spaces as `%20`.
+- In assistant UI responses, use the link format required by the execution environment; include relative path text when possible.
 
-### Scope
-- Repository purpose: standalone Russian localization mod only.
-- Allowed domain: localization content + packaging/release metadata.
-- Forbidden: gameplay logic, Script Extender content, unrelated assets.
-- Keep repository source-only.
-- Never commit `.pak` or temporary build artifacts.
+---
 
-### Canonical Paths
-- Mod sources: `Mods/DnD 5.5e AIO Russian`
-- Russian localization: `Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml`
-- Mod metadata: `Mods/DnD 5.5e AIO Russian/meta.lsx`
-- Build script (single source of build truth): `scripts/build.ps1`
-- CI workflow: `.gitea/workflows/build.yml`
-- Glossary (primary terminology reference): `glossary/glossary.normalized.json`
-- Action catalog and command playbooks: `ACTIONS.md`
-- Upstream English reference: `https://github.com/Yoonmoonsik/dnd55e/blob/main/Mods/DnD2024_897914ef-5c96-053c-44af-0be823f895fe/Localization/English/english.xml`
+## Git Workflow (MUST)
+- Never commit/push without explicit user approval.
+- After approval → commit + push immediately.
+- Commit messages: Russian, factual (what was done).
+- Branch (`fix/*` or `feat/*`): ask once before the first file-changing task that may lead to commit; reuse decision for all subsequent tasks in same dialogue.
 
-### Packaging Invariants
-- `.pak` must contain only BG3 mod structure under `Mods/...`.
-- Required content in `.pak`:
-  - `Mods/DnD 5.5e AIO Russian/meta.lsx`
-  - `Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml`
-- Must not leak into `.pak`: `.git`, `.gitea`, `scripts`, `tools`, `.tools`, `build`, staging dirs.
-- Staging for packaging must be in `%TEMP%`, not in dot-prefixed repo dirs.
+After work in `fix/*` or `feat/*`:
+1. MR → main
+2. merge → main + delete branch
 
-### Build/CI Contract
-- CI workflow stays thin:
-  1. prepare workspace
+Push failure:
+- retry ≤2 times, 3s delay
+
+Release link:
+- provide `[version](url)` immediately after tag push, without waiting for CI
+
+---
+
+## Scope (MUST)
+- Repo = Russian localization mod only.
+
+Allowed:
+- localization content
+- packaging/release metadata
+
+Forbidden:
+- gameplay logic
+- Script Extender
+- unrelated assets
+
+- Repo must remain source-only.
+- Never commit `.pak` or build artifacts.
+
+---
+
+## Paths (MUST)
+- Mod: `Mods/DnD 5.5e AIO Russian`
+- Localization: `Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml`
+- Metadata: `Mods/DnD 5.5e AIO Russian/meta.lsx`
+- Build: `scripts/build.ps1` _(single source of build truth)_
+- CI: `.gitea/workflows/build.yml`
+- Glossary: `glossary/glossary.normalized.json` _(primary terminology reference)_
+- Actions: `ACTIONS.md`
+- Upstream EN reference: `https://github.com/Yoonmoonsik/dnd55e/blob/main/Mods/DnD2024_897914ef-5c96-053c-44af-0be823f895fe/Localization/English/english.xml`
+
+---
+
+## Packaging (MUST)
+- `.pak` contains ONLY `Mods/...`
+
+Required:
+- `meta.lsx`
+- `russian.xml`
+
+Forbidden in `.pak`:
+- `.git`, `.gitea`
+- `scripts`, `tools`, `.tools`
+- `build`, staging dirs
+
+Staging:
+- use `%TEMP%`
+- not inside repo
+
+---
+
+## Build & CI (MUST)
+Flow:
+1. prepare
 2. download Divine
-  3. call `scripts/build.ps1`
-  4. publish tag archive
-- Expected build outputs:
-  - `build/DnD 5.5e AIO Russian.pak`
+3. run `scripts/build.ps1`
+4. publish
+
+Outputs:
+- `build/*.pak`
 - `build/info.json`
-  - `build/DnD 5.5e AIO Russian <tag>.zip` (for tag builds)
-- Release ZIP must include only `.pak` + `info.json`.
-- CI triggers: tag `v*` and manual dispatch; not every push to `main`.
+- `build/*.zip` (tag only)
 
-### Version/Release Rules
-- Read release version only from `save/region/node[@id="ModuleSettings"]/children/node[@id="ModuleInfo"]/attribute[@id="Version64"]` via explicit XML parsing.
-- `PublishVersion` must not be changed during release preparation.
-- Release tag must match the source-of-truth version.
-- Decision logic before tagging:
-  1. If `ModuleInfo/Version64` was manually changed (e.g. BG3 Toolkit), use matching tag and release.
-  2. If `ModuleInfo/Version64` equals latest released version, bump version first (e.g. `scripts/set-version.ps1 -VersionTag <tag>`), commit, then create/push tag.
-- `scripts/build.ps1` derives release `Version64` from tag and writes it to generated `info.json` and staged `meta.lsx`.
+Release ZIP:
+- only `.pak` + `info.json`
 
-### info.json Contract
-- Top-level keys: `Mods`, `MD5`.
-- Per-mod keys: `Author`, `Name`, `Folder`, `Version`, `Description`, `UUID`, `Created`, `Dependencies`, `Group`.
-- `Dependencies` is an array of UUIDs.
-- Current dependency UUID: `897914ef-5c96-053c-44af-0be823f895fe`.
+Triggers:
+- automatic: push tag `v*`
+- manual: workflow_dispatch
+- branch pushes without tag MUST NOT publish release artifacts
 
-### Git Collaboration Policy (Project-Specific)
-- Commit messages and comments: Russian.
-- Commit message content: what was done (not what should be done).
-- If changes affect `.pak` contents or build/release flow: propose releasing next version.
-- For released versions in user-facing messages: provide direct archive link in Markdown format `[version](url)` when derivable (acceptable immediately after tag push, even before CI finishes).
+---
 
-### Cleanup (Project-Specific)
-- Ignored/temp patterns include: `build/`, `build-stage*`, `.tools/`, `*.pak`.
+## Versioning (CRITICAL)
+Source of truth:
+`ModuleInfo/Version64` — read via explicit XML parsing:
+`save/region[@id="Config"]/node[@id="root"]/children/node[@id="ModuleInfo"]/attribute[@id="Version64"]`
+
+Rules:
+- do not change `PublishVersion`
+- tag MUST match version
+
+Before tag:
+1. if version already changed → use it
+2. if same as last → bump:
+   `scripts/set-version.ps1 -VersionTag <tag>`
+
+`build.ps1`:
+- derives version from tag
+- writes to `info.json` + staged `meta.lsx`
+
+Conflict resolution (MUST):
+- before release, `Version64` in `meta.lsx` MUST equal target tag version
+- if mismatch, run `scripts/set-version.ps1 -VersionTag <tag>` and re-check
+- if still mismatch, release is blocked
+
+---
+
+## info.json (MUST)
+Root:
+- `Mods`, `MD5`
+
+Per mod:
+- Author, Name, Folder, Version
+- Description, UUID, Created
+- Dependencies (array), Group
+
+Dependency UUID:
+`897914ef-5c96-053c-44af-0be823f895fe`
+
+---
+
+## Guardrails (MUST)
+
+Before commit:
+- scope valid (localization/metadata only)
+- no forbidden content
+- no build artifacts (`.pak`, `build/`, staging)
+- no temp/debug artifacts; ignored patterns MUST be present in `.gitignore`: `build/`, `build-stage*`, `.tools/`, `*.pak`
+- packaging invariants intact
+- version consistent (if applicable)
+
+Before push:
+- explicit user approval
+- commit message valid (RU, factual)
+
+Before release:
+- version == tag
+- version bumped if needed
+- CI/build contract valid
+- outputs correct (no extra files)
+
+---
+
+## Release & Changelog (MUST)
+
+- Every release MUST include changelog.
+
+Changelog:
+- language: Russian
+- concise, user-facing
+- describe WHAT changed
+- group logically
+
+Sources:
+- prefer diff over commits
+
+Diff rules:
+- inspect real file changes
+
+Localization (`russian.xml`):
+- added / changed / removed strings
+- summarize user-visible impact (UI, spells, descriptions)
+
+Metadata / CI:
+- describe effect, not raw edits
+
+Large diff:
+- group + summarize
+
+If no visible changes:
+- state "техническое обновление"
+
+Before release:
+- generate changelog draft
+- ask for approval
+
+Approval gates:
+- Gate A: explicit approval for commit/push (code/content changes)
+- Gate B: explicit approval for release publish (after changelog draft)
+
+Release message:
+- version
+- changelog
+- `[version](url)` if derivable
+
+Do not:
+- invent changes
+- include internal noise
+
+---
+
+## Rules Maintenance (MUST)
+- Changes to `AGENTS.md` / `ACTIONS.md`: prefer compressed, machine-readable edits.
+- Keep updates minimal and non-duplicative: merge overlapping points, remove redundancy, preserve intent.

Mods/DnD 5.5e AIO Russian/meta.lsx

@@ -9,16 +9,16 @@
                     <children>
                         <node id="ModuleShortDesc">
                             <attribute id="Folder" type="LSString" value="DnD2024_897914ef-5c96-053c-44af-0be823f895fe"/>
-                            <attribute id="MD5" type="LSString" value="ac497558b070a635abecd7d23d4a3125"/>
+                            <attribute id="MD5" type="LSString" value="4bd42ca93f895d1ec521a286bea09ef2"/>
                             <attribute id="Name" type="LSString" value="DnD 5.5e All-in-One BEYOND"/>
                             <attribute id="PublishHandle" type="uint64" value="4419649"/>
                             <attribute id="UUID" type="guid" value="897914ef-5c96-053c-44af-0be823f895fe"/>
-                            <attribute id="Version64" type="int64" value="144396678084952064"/>
+                            <attribute id="Version64" type="int64" value="144396675937468416"/>
                         </node>
                     </children>
                 </node>
                 <node id="ModuleInfo">
-                    <attribute id="Author" type="LSString" value="MikhailRaw"/>
+                    <attribute id="Author" type="LSString" value="Underslumber Team"/>
                     <attribute id="CharacterCreationLevelName" type="FixedString" value=""/>
                     <attribute id="Description" type="LSString" value="Русский перевод мода DnD 5.5e All-in-One BEYOND. Перевод ещё в разработке: AI помогает быстро обновлять тексты, а финальные правки и качество мы проверяем вручную."/>
                     <attribute id="FileSize" type="uint64" value="2488095"/>
@@ -32,7 +32,7 @@
                     <attribute id="PublishHandle" type="uint64" value="5965149"/>
                     <attribute id="StartupLevelName" type="FixedString" value=""/>
                     <attribute id="UUID" type="FixedString" value="6401e84d-daf2-416d-adeb-99c03a2487a6"/>
-                    <attribute id="Version64" type="int64" value="281481419161600"/>
+                    <attribute id="Version64" type="int64" value="281487861612544"/>
                     <children>
                         <node id="PublishVersion">
                             <attribute id="Version64" type="int64" value="281477124194304"/>

README.md

@@ -1,12 +1,11 @@
 # DnD 5.5e All-in-One BEYOND Russian Localization
 
-Русский перевод мода **DnD 5.5e All-in-One BEYOND** для **Baldur's Gate 3**.
+Русская локализация [**DnD 5.5e All-in-One BEYOND**](https://github.com/Yoonmoonsik/dnd55e) для **Baldur's Gate 3**.
 
-Оригинальный репозиторий:
-[Yoonmoonsik/dnd55e](https://github.com/Yoonmoonsik/dnd55e)
+Публикация на [mod.io](https://mod.io/g/baldursgate3/m/dnd-55e-all-in-one-beyond-russian-localization).
 
 ## О моде
 
-**DnD 5.5e All-in-One BEYOND** переносит в Baldur's Gate 3 контент и механики, вдохновлённые Dungeons & Dragons 5.5e. Мод расширяет игру новыми и переработанными элементами, включая классы, предыстории, таланты, расы, заклинания и другие связанные системы.
+Русский перевод мода **DnD 5.5e All-in-One BEYOND**, который переносит в **Baldur's Gate 3** широкий пласт контента и правил **D&D 5.5e / PHB 2024**.
 
-Этот проект предназначен для русской локализации оригинального мода и его текстового контента.
+Локализация поддерживается в темпе с апстримом, который сейчас развивается в сторону более полного охвата классов, рас, предысторий, фитов и заклинаний.

glossary/glossary.normalized.json

@@ -459,7 +459,7 @@
   "Locate animals or plants": "Поиск животных или растений",
   "Locate creature": "Поиск существа",
   "Locate object": "Поиск предмета",
-  "Long Rest": "долгий отдых",
+  "Long Rest": "Долгий отдых",
   "Longbow": "Длинный лук",
   "Longstrider": "Скороход",
   "Longsword": "Длинный меч",
@@ -695,7 +695,7 @@
   "Shillelagh": "Шиллейла",
   "Shocking Grasp": "Шоковое прикосновение",
   "Shocking grasp": "Электрошок",
-  "Short Rest": "короткий отдых",
+  "Short Rest": "Короткий отдых",
   "Shortbow": "Короткий лук",
   "Shortsword": "Короткий меч",
   "Sickle": "Серп",

scripts/apply-translation-edits.ps1

@@ -0,0 +1,210 @@
+param(
+    [string]$RussianPath = "Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml",
+    [Parameter(Mandatory = $true)]
+    [string]$EditsPath
+)
+
+$ErrorActionPreference = "Stop"
+
+function Read-XmlDocument {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$Path
+    )
+
+    $resolvedPath = [System.IO.Path]::GetFullPath($Path)
+    if (-not (Test-Path -LiteralPath $resolvedPath)) {
+        throw "XML file was not found: '$resolvedPath'."
+    }
+
+    [xml]$xml = Get-Content -LiteralPath $resolvedPath -Raw
+    if ($null -eq $xml.SelectSingleNode('/contentList')) {
+        throw "XML file does not contain '/contentList': '$resolvedPath'."
+    }
+
+    return @{
+        Path = $resolvedPath
+        Xml = $xml
+    }
+}
+
+function Get-ContentNodeMap {
+    param(
+        [Parameter(Mandatory = $true)]
+        [xml]$Xml
+    )
+
+    $map = @{}
+    foreach ($node in $Xml.SelectNodes('/contentList/content')) {
+        $contentUid = [string]$node.GetAttribute("contentuid")
+        if ([string]::IsNullOrWhiteSpace($contentUid)) {
+            continue
+        }
+
+        if ($map.ContainsKey($contentUid)) {
+            throw "Duplicate contentuid found in target XML: '$contentUid'."
+        }
+
+        $map[$contentUid] = $node
+    }
+
+    return $map
+}
+
+function Assert-UniqueEditContentUid {
+    param(
+        [AllowEmptyCollection()]
+        [Parameter(Mandatory = $true)]
+        [System.Collections.Generic.HashSet[string]]$Seen,
+        [Parameter(Mandatory = $true)]
+        [string]$ContentUid,
+        [Parameter(Mandatory = $true)]
+        [string]$Section
+    )
+
+    if (-not $Seen.Add($ContentUid)) {
+        throw "Edits file contains duplicate contentuid '$ContentUid' in '$Section'."
+    }
+}
+
+$russianDocument = Read-XmlDocument -Path $RussianPath
+$temporaryRussianPath = "$($russianDocument.Path).tmp"
+$validateScriptPath = Join-Path $PSScriptRoot "validate-translation-xml.ps1"
+
+if (-not (Test-Path -LiteralPath $validateScriptPath)) {
+    throw "Validation script was not found: '$validateScriptPath'."
+}
+
+if (Test-Path -LiteralPath $temporaryRussianPath) {
+    Remove-Item -LiteralPath $temporaryRussianPath -Force
+}
+
+Copy-Item -LiteralPath $russianDocument.Path -Destination $temporaryRussianPath -Force
+$russianDocument = Read-XmlDocument -Path $temporaryRussianPath
+$resolvedEditsPath = [System.IO.Path]::GetFullPath($EditsPath)
+if (-not (Test-Path -LiteralPath $resolvedEditsPath)) {
+    throw "Edits file was not found: '$resolvedEditsPath'."
+}
+
+$edits = Get-Content -LiteralPath $resolvedEditsPath -Raw | ConvertFrom-Json -Depth 10
+if ($null -eq $edits) {
+    throw "Edits file is empty or invalid JSON: '$resolvedEditsPath'."
+}
+
+$contentListNode = $russianDocument.Xml.SelectSingleNode('/contentList')
+if ($null -eq $contentListNode) {
+    throw "Target russian.xml does not contain '/contentList': '$($russianDocument.Path)'."
+}
+
+$nodeMap = Get-ContentNodeMap -Xml $russianDocument.Xml
+$updatedEntries = New-Object System.Collections.Generic.List[string]
+$addedEntries = New-Object System.Collections.Generic.List[string]
+$seenEditContentUids = [System.Collections.Generic.HashSet[string]]::new()
+
+$updates = @()
+if ($edits.PSObject.Properties.Name -contains "updates" -and $null -ne $edits.updates) {
+    $updates = @($edits.updates)
+}
+
+foreach ($edit in $updates) {
+    $contentUid = [string]$edit.contentuid
+    if ([string]::IsNullOrWhiteSpace($contentUid)) {
+        throw "Each update entry must contain non-empty 'contentuid'."
+    }
+
+    Assert-UniqueEditContentUid -Seen $seenEditContentUids -ContentUid $contentUid -Section "updates"
+
+    if (-not $nodeMap.ContainsKey($contentUid)) {
+        throw "Target russian.xml does not contain contentuid '$contentUid' for update."
+    }
+
+    $node = $nodeMap[$contentUid]
+    if ($edit.PSObject.Properties.Name -contains "version" -and -not [string]::IsNullOrWhiteSpace([string]$edit.version)) {
+        $node.SetAttribute("version", [string]$edit.version)
+    }
+
+    if ($edit.PSObject.Properties.Name -contains "text") {
+        if ([string]::IsNullOrWhiteSpace([string]$edit.text)) {
+            throw "Update entry '$contentUid' must contain non-empty 'text' when provided."
+        }
+        $node.InnerText = [string]$edit.text
+    }
+
+    $updatedEntries.Add($contentUid) | Out-Null
+}
+
+$adds = @()
+if ($edits.PSObject.Properties.Name -contains "adds" -and $null -ne $edits.adds) {
+    $adds = @($edits.adds)
+}
+
+if (($updates.Count -eq 0) -and ($adds.Count -eq 0)) {
+    if (Test-Path -LiteralPath $temporaryRussianPath) {
+        Remove-Item -LiteralPath $temporaryRussianPath -Force
+    }
+    Write-Host "[apply-translation-edits.ps1] No edits requested. Original russian.xml left unchanged."
+    return
+}
+
+foreach ($edit in $adds) {
+    $contentUid = [string]$edit.contentuid
+    $version = [string]$edit.version
+    $text = [string]$edit.text
+
+    if ([string]::IsNullOrWhiteSpace($contentUid)) {
+        throw "Each add entry must contain non-empty 'contentuid'."
+    }
+
+    Assert-UniqueEditContentUid -Seen $seenEditContentUids -ContentUid $contentUid -Section "adds"
+
+    if ($nodeMap.ContainsKey($contentUid)) {
+        throw "Target russian.xml already contains contentuid '$contentUid'; use 'updates' instead of 'adds'."
+    }
+
+    if ([string]::IsNullOrWhiteSpace($version)) {
+        throw "Add entry '$contentUid' must contain non-empty 'version'."
+    }
+
+    if ([string]::IsNullOrWhiteSpace($text)) {
+        throw "Add entry '$contentUid' must contain non-empty 'text'."
+    }
+
+    $newNode = $russianDocument.Xml.CreateElement("content")
+    $newNode.SetAttribute("contentuid", $contentUid)
+    $newNode.SetAttribute("version", $version)
+    $newNode.InnerText = $text
+    [void]$contentListNode.AppendChild($newNode)
+    $nodeMap[$contentUid] = $newNode
+    $addedEntries.Add($contentUid) | Out-Null
+}
+
+$settings = New-Object System.Xml.XmlWriterSettings
+$settings.Encoding = New-Object System.Text.UTF8Encoding($true)
+$settings.Indent = $true
+$settings.IndentChars = "  "
+$settings.NewLineChars = "`n"
+$settings.NewLineHandling = [System.Xml.NewLineHandling]::Replace
+
+$writer = [System.Xml.XmlWriter]::Create($russianDocument.Path, $settings)
+try {
+    $russianDocument.Xml.WriteTo($writer)
+} finally {
+    $writer.Dispose()
+}
+
+try {
+    & $validateScriptPath -XmlPath $temporaryRussianPath
+    Move-Item -LiteralPath $temporaryRussianPath -Destination $RussianPath -Force
+} finally {
+    if (Test-Path -LiteralPath $temporaryRussianPath) {
+        Remove-Item -LiteralPath $temporaryRussianPath -Force
+    }
+}
+
+Write-Host "[apply-translation-edits.ps1] Updated entries: $($updatedEntries.Count); Added entries: $($addedEntries.Count)."
+if ($updatedEntries.Count -gt 0) {
+    Write-Host "[apply-translation-edits.ps1] Updated contentuid: $($updatedEntries -join ', ')"
+}
+if ($addedEntries.Count -gt 0) {
+    Write-Host "[apply-translation-edits.ps1] Added contentuid: $($addedEntries -join ', ')"
+}

scripts/build.ps1

@@ -7,7 +7,7 @@ param(
     [string]$ArchiveBaseName = "DnD 5.5e AIO Russian",
     [string]$ModName = "DnD 5.5e All-in-One BEYOND Russian Localization",
     [string]$ModUuid = "6401e84d-daf2-416d-adeb-99c03a2487a6",
-    [string]$ModAuthor = "MikhailRaw",
+    [string]$ModAuthor = "Underslumber Team",
     [string]$ModDescription = "Русская локализация мода, который добавляет и обновляет контент в соответствии с правилами DnD 5.5e и другими источниками, включая предыстории, классы, таланты, расы, заклинания и многое другое. Это отдельный мод локализации и он требует установленный оригинальный мод.",
     [string]$ModVersion64 = "36028797018963968",
     [string]$ModGroup = "6401e84d-daf2-416d-adeb-99c03a2487a6",
@@ -101,10 +101,10 @@ if (-not (Test-Path -LiteralPath $stagedMetaPath)) {
     throw "Staged meta.lsx was not found: '$stagedMetaPath'."
 }
 
-$stagedMetaContent = Get-Content -LiteralPath $stagedMetaPath -Raw
+$utf8Encoding = [System.Text.UTF8Encoding]::new($false)
+$stagedMetaContent = [System.IO.File]::ReadAllText($stagedMetaPath, $utf8Encoding)
 $stagedMetaContent = $stagedMetaContent -replace '(<attribute id="Version64" type="int64" value=")\d+("/>)', "`${1}$resolvedVersion64`${2}"
-$utf8Bom = New-Object System.Text.UTF8Encoding($true)
-[System.IO.File]::WriteAllText($stagedMetaPath, $stagedMetaContent, $utf8Bom)
+[System.IO.File]::WriteAllText($stagedMetaPath, $stagedMetaContent, $utf8Encoding)
 
 Write-Host "[build.ps1] Staged source tree:"
 Get-ChildItem -Recurse $stagingPath | Select-Object FullName, Length | Format-Table -AutoSize

scripts/compare-translation.ps1

@@ -0,0 +1,209 @@
+param(
+    [string]$EnglishPath = ".cache/upstream/english.xml",
+    [string]$RussianPath = "Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml",
+    [string]$OutputDir = "build/translation-diff"
+)
+
+$ErrorActionPreference = "Stop"
+
+function Get-LocalizationEntries {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$Path
+    )
+
+    $resolvedPath = [System.IO.Path]::GetFullPath($Path)
+    if (-not (Test-Path -LiteralPath $resolvedPath)) {
+        throw "Localization XML was not found: '$resolvedPath'."
+    }
+
+    [xml]$xml = Get-Content -LiteralPath $resolvedPath -Raw
+    $nodes = $xml.SelectNodes('/contentList/content')
+    if ($null -eq $nodes) {
+        throw "Localization XML does not contain '/contentList/content' nodes: '$resolvedPath'."
+    }
+
+    $entries = @{}
+    foreach ($node in $nodes) {
+        $contentUid = [string]$node.GetAttribute("contentuid")
+        if ([string]::IsNullOrWhiteSpace($contentUid)) {
+            throw "Localization XML contains a content node without 'contentuid': '$resolvedPath'."
+        }
+
+        if ($entries.ContainsKey($contentUid)) {
+            throw "Localization XML contains duplicate contentuid '$contentUid': '$resolvedPath'."
+        }
+
+        $version = [string]$node.GetAttribute("version")
+        if ([string]::IsNullOrWhiteSpace($version)) {
+            throw "Localization XML contains contentuid '$contentUid' with empty 'version': '$resolvedPath'."
+        }
+
+        $entries[$contentUid] = [ordered]@{
+            contentuid = $contentUid
+            version = $version
+            text = [string]$node.InnerText
+        }
+    }
+
+    return $entries
+}
+
+$resolvedOutputDir = [System.IO.Path]::GetFullPath($OutputDir)
+New-Item -ItemType Directory -Path $resolvedOutputDir -Force | Out-Null
+
+$englishEntries = Get-LocalizationEntries -Path $EnglishPath
+$russianEntries = Get-LocalizationEntries -Path $RussianPath
+
+$missingInRussian = New-Object System.Collections.Generic.List[object]
+$versionMismatch = New-Object System.Collections.Generic.List[object]
+$staleOnlyInRussian = New-Object System.Collections.Generic.List[object]
+
+foreach ($contentUid in ($englishEntries.Keys | Sort-Object)) {
+    $englishEntry = $englishEntries[$contentUid]
+    if (-not $russianEntries.ContainsKey($contentUid)) {
+        $missingInRussian.Add([pscustomobject]@{
+            contentuid = $contentUid
+            englishVersion = $englishEntry.version
+            englishText = $englishEntry.text
+        }) | Out-Null
+        continue
+    }
+
+    $russianEntry = $russianEntries[$contentUid]
+    if ($englishEntry.version -ne $russianEntry.version) {
+        $versionMismatch.Add([pscustomobject]@{
+            contentuid = $contentUid
+            englishVersion = $englishEntry.version
+            russianVersion = $russianEntry.version
+            englishText = $englishEntry.text
+            russianText = $russianEntry.text
+        }) | Out-Null
+    }
+}
+
+foreach ($contentUid in ($russianEntries.Keys | Sort-Object)) {
+    if (-not $englishEntries.ContainsKey($contentUid)) {
+        $russianEntry = $russianEntries[$contentUid]
+        $staleOnlyInRussian.Add([pscustomobject]@{
+            contentuid = $contentUid
+            russianVersion = $russianEntry.version
+            russianText = $russianEntry.text
+        }) | Out-Null
+    }
+}
+
+$summary = [ordered]@{
+    generatedAt = (Get-Date).ToString("o")
+    englishPath = [System.IO.Path]::GetFullPath($EnglishPath)
+    russianPath = [System.IO.Path]::GetFullPath($RussianPath)
+    englishCount = $englishEntries.Count
+    russianCount = $russianEntries.Count
+    missingInRussianCount = $missingInRussian.Count
+    versionMismatchCount = $versionMismatch.Count
+    staleOnlyInRussianCount = $staleOnlyInRussian.Count
+    missingInRussian = $missingInRussian
+    versionMismatch = $versionMismatch
+    staleOnlyInRussian = $staleOnlyInRussian
+}
+
+$summaryJsonPath = Join-Path $resolvedOutputDir "summary.json"
+$summaryMdPath = Join-Path $resolvedOutputDir "summary.md"
+$candidatesJsonPath = Join-Path $resolvedOutputDir "candidates.json"
+
+$summary | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath $summaryJsonPath -Encoding utf8
+
+$candidates = [ordered]@{
+    generatedAt = (Get-Date).ToString("o")
+    source = [ordered]@{
+        englishPath = [System.IO.Path]::GetFullPath($EnglishPath)
+        russianPath = [System.IO.Path]::GetFullPath($RussianPath)
+    }
+    updates = @(
+        $versionMismatch | ForEach-Object {
+            [ordered]@{
+                contentuid = $_.contentuid
+                version = $_.englishVersion
+                text = $_.russianText
+                englishText = $_.englishText
+                russianVersion = $_.russianVersion
+            }
+        }
+    )
+    adds = @(
+        $missingInRussian | ForEach-Object {
+            [ordered]@{
+                contentuid = $_.contentuid
+                version = $_.englishVersion
+                text = ""
+                englishText = $_.englishText
+            }
+        }
+    )
+}
+
+$candidates | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath $candidatesJsonPath -Encoding utf8
+
+$isUpToDate = ($missingInRussian.Count -eq 0) -and ($versionMismatch.Count -eq 0) -and ($staleOnlyInRussian.Count -eq 0)
+
+$mdLines = @(
+    "# Translation diff summary",
+    "",
+    "- Generated: $($summary.generatedAt)",
+    "- English entries: $($summary.englishCount)",
+    "- Russian entries: $($summary.russianCount)",
+    "- Missing in Russian: $($summary.missingInRussianCount)",
+    "- Version mismatches: $($summary.versionMismatchCount)",
+    "- Stale only in Russian: $($summary.staleOnlyInRussianCount)",
+    ""
+)
+
+if ($isUpToDate) {
+    $mdLines += "Перевод уже актуален, дополнительные действия не требуются."
+} else {
+    $mdLines += ""
+    $mdLines += "## Agent workflow"
+    $mdLines += "1. Refresh upstream cache: ``scripts/get-upstream-english.ps1``"
+    $mdLines += "2. Refresh diff reports: ``scripts/compare-translation.ps1``"
+    $mdLines += "3. Fill translated texts in ``build/translation-diff/candidates.json``"
+    $mdLines += "4. Apply only prepared edits: ``scripts/apply-translation-edits.ps1 -EditsPath build/translation-diff/candidates.json``"
+}
+
+$mdLines += ""
+$mdLines += "## Missing in Russian"
+if ($missingInRussian.Count -eq 0) {
+    $mdLines += "- none"
+} else {
+    $mdLines += ($missingInRussian | Select-Object -First 50 | ForEach-Object {
+        "- ``$($_.contentuid)`` v$($_.englishVersion): $($_.englishText)"
+    })
+}
+
+$mdLines += ""
+$mdLines += "## Version mismatches"
+if ($versionMismatch.Count -eq 0) {
+    $mdLines += "- none"
+} else {
+    $mdLines += ($versionMismatch | Select-Object -First 50 | ForEach-Object {
+        "- ``$($_.contentuid)`` en=v$($_.englishVersion), ru=v$($_.russianVersion)"
+    })
+}
+
+$mdLines += ""
+$mdLines += "## Stale only in Russian"
+if ($staleOnlyInRussian.Count -eq 0) {
+    $mdLines += "- none"
+} else {
+    $mdLines += ($staleOnlyInRussian | Select-Object -First 50 | ForEach-Object {
+        "- ``$($_.contentuid)`` v$($_.russianVersion): $($_.russianText)"
+    })
+}
+
+Set-Content -LiteralPath $summaryMdPath -Value $mdLines -Encoding utf8
+
+Write-Host "[compare-translation.ps1] Summary written to '$summaryJsonPath' and '$summaryMdPath'."
+Write-Host "[compare-translation.ps1] Editable candidate file written to '$candidatesJsonPath'."
+Write-Host "[compare-translation.ps1] Missing=$($missingInRussian.Count); VersionMismatch=$($versionMismatch.Count); StaleOnlyInRussian=$($staleOnlyInRussian.Count)."
+if ($isUpToDate) {
+    Write-Host "[compare-translation.ps1] Перевод уже актуален, дополнительные действия не требуются."
+}

scripts/get-upstream-english.ps1

@@ -0,0 +1,44 @@
+param(
+    [string]$UpstreamEnglishUrl = "https://raw.githubusercontent.com/Yoonmoonsik/dnd55e/main/Mods/DnD2024_897914ef-5c96-053c-44af-0be823f895fe/Localization/English/english.xml",
+    [string]$OutputPath = ".cache/upstream/english.xml",
+    [switch]$Force
+)
+
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($UpstreamEnglishUrl)) {
+    throw "UpstreamEnglishUrl must not be empty."
+}
+
+$resolvedOutputPath = [System.IO.Path]::GetFullPath($OutputPath)
+$outputDirectory = Split-Path -Parent $resolvedOutputPath
+if (-not (Test-Path -LiteralPath $outputDirectory)) {
+    New-Item -ItemType Directory -Path $outputDirectory -Force | Out-Null
+}
+
+$requestParameters = @{
+    Uri = $UpstreamEnglishUrl
+    OutFile = $resolvedOutputPath
+    UseBasicParsing = $true
+    TimeoutSec = 120
+}
+
+if ($Force) {
+    $requestParameters["Headers"] = @{
+        "Cache-Control" = "no-cache"
+    }
+}
+
+Invoke-WebRequest @requestParameters
+
+[xml]$englishXml = Get-Content -LiteralPath $resolvedOutputPath -Raw
+$rootNode = $englishXml.SelectSingleNode('/contentList')
+if ($null -eq $rootNode) {
+    throw "Downloaded file is not a valid BG3 localization XML: '$resolvedOutputPath'."
+}
+
+$contentCount = $englishXml.SelectNodes('/contentList/content').Count
+$fileInfo = Get-Item -LiteralPath $resolvedOutputPath
+
+Write-Host "[get-upstream-english.ps1] Saved upstream english.xml to '$resolvedOutputPath'."
+Write-Host "[get-upstream-english.ps1] Entries: $contentCount; Size: $($fileInfo.Length) bytes; Updated: $($fileInfo.LastWriteTime.ToString("o"))."

scripts/set-version.ps1

@@ -35,7 +35,8 @@ if (-not (Test-Path -LiteralPath $resolvedMetaPath)) {
 }
 
 $resolvedVersion64 = Convert-VersionTagToVersion64 -Tag $VersionTag
-$metaContent = Get-Content -LiteralPath $resolvedMetaPath -Raw
+$utf8Encoding = [System.Text.UTF8Encoding]::new($false)
+$metaContent = [System.IO.File]::ReadAllText($resolvedMetaPath, $utf8Encoding)
 [xml]$metaXml = $metaContent
 
 # Explicitly target ModuleInfo/Version64 via XML path to avoid touching Dependencies/PublishVersion.
@@ -57,7 +58,6 @@ $updatedMeta = [regex]::Replace(
     1
 )
 
-$utf8Bom = New-Object System.Text.UTF8Encoding($true)
-[System.IO.File]::WriteAllText($resolvedMetaPath, $updatedMeta, $utf8Bom)
+[System.IO.File]::WriteAllText($resolvedMetaPath, $updatedMeta, $utf8Encoding)
 
 Write-Host "[set-version.ps1] Updated '$resolvedMetaPath' to Version64=$resolvedVersion64 (from tag '$VersionTag')."

scripts/update-translation.ps1

@@ -0,0 +1,71 @@
+param(
+    [string]$RussianPath = "Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml",
+    [string]$EnglishPath = ".cache/upstream/english.xml",
+    [string]$OutputDir = "build/translation-diff",
+    [string]$EditsPath = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+$getUpstreamScriptPath = Join-Path $PSScriptRoot "get-upstream-english.ps1"
+$compareScriptPath = Join-Path $PSScriptRoot "compare-translation.ps1"
+$applyScriptPath = Join-Path $PSScriptRoot "apply-translation-edits.ps1"
+
+foreach ($scriptPath in @($getUpstreamScriptPath, $compareScriptPath, $applyScriptPath)) {
+    if (-not (Test-Path -LiteralPath $scriptPath)) {
+        throw "Required script was not found: '$scriptPath'."
+    }
+}
+
+$resolvedOutputDir = [System.IO.Path]::GetFullPath($OutputDir)
+$resolvedProvidedEditsPath = ""
+if (-not [string]::IsNullOrWhiteSpace($EditsPath)) {
+    $resolvedProvidedEditsPath = [System.IO.Path]::GetFullPath($EditsPath)
+}
+$workingDiffDir = Join-Path $env:TEMP ("bg3-translation-update-" + [guid]::NewGuid().ToString("N"))
+New-Item -ItemType Directory -Path $workingDiffDir -Force | Out-Null
+
+try {
+    & $getUpstreamScriptPath -OutputPath $EnglishPath -Force
+    & $compareScriptPath -EnglishPath $EnglishPath -RussianPath $RussianPath -OutputDir $workingDiffDir
+
+    New-Item -ItemType Directory -Path $resolvedOutputDir -Force | Out-Null
+    Get-ChildItem -LiteralPath $workingDiffDir | ForEach-Object {
+        $destinationPath = Join-Path $resolvedOutputDir $_.Name
+        if ($resolvedProvidedEditsPath -and ([System.IO.Path]::GetFullPath($destinationPath) -eq $resolvedProvidedEditsPath) -and (Test-Path -LiteralPath $resolvedProvidedEditsPath)) {
+            return
+        }
+        Copy-Item -LiteralPath $_.FullName -Destination $resolvedOutputDir -Recurse -Force
+    }
+
+    $summaryJsonPath = Join-Path $workingDiffDir "summary.json"
+    if (-not (Test-Path -LiteralPath $summaryJsonPath)) {
+        throw "Translation summary was not found: '$summaryJsonPath'."
+    }
+
+    $summary = Get-Content -LiteralPath $summaryJsonPath -Raw | ConvertFrom-Json -Depth 10
+    $hasDiff = ($summary.missingInRussianCount -gt 0) -or ($summary.versionMismatchCount -gt 0) -or ($summary.staleOnlyInRussianCount -gt 0)
+
+    if (-not $hasDiff) {
+        Write-Host "[update-translation.ps1] Перевод уже актуален, дополнительные действия не требуются."
+        return
+    }
+
+    if ([string]::IsNullOrWhiteSpace($EditsPath)) {
+        Write-Host "[update-translation.ps1] Найдены изменения перевода. Подготовьте правки в '$([System.IO.Path]::GetFullPath((Join-Path $resolvedOutputDir "candidates.json")))' и затем запустите повторно с '-EditsPath'."
+        return
+    }
+
+    $effectiveEditsPath = [System.IO.Path]::GetFullPath($EditsPath)
+    if (-not (Test-Path -LiteralPath $effectiveEditsPath)) {
+        throw "Prepared edits file was not found: '$effectiveEditsPath'."
+    }
+
+    & $applyScriptPath -RussianPath $RussianPath -EditsPath $effectiveEditsPath
+
+    Write-Host "[update-translation.ps1] Обновление перевода завершено. Результат записан в '$([System.IO.Path]::GetFullPath($RussianPath))'."
+} finally {
+    if (Test-Path -LiteralPath $workingDiffDir) {
+        Remove-Item -LiteralPath $workingDiffDir -Recurse -Force
+    }
+}

scripts/validate-translation-xml.ps1

@@ -0,0 +1,41 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$XmlPath
+)
+
+$ErrorActionPreference = "Stop"
+
+$resolvedXmlPath = [System.IO.Path]::GetFullPath($XmlPath)
+if (-not (Test-Path -LiteralPath $resolvedXmlPath)) {
+    throw "XML file was not found: '$resolvedXmlPath'."
+}
+
+[xml]$xml = Get-Content -LiteralPath $resolvedXmlPath -Raw
+$contentListNode = $xml.SelectSingleNode('/contentList')
+if ($null -eq $contentListNode) {
+    throw "XML validation failed: missing '/contentList' in '$resolvedXmlPath'."
+}
+
+$contentNodes = $xml.SelectNodes('/contentList/content')
+if ($null -eq $contentNodes -or $contentNodes.Count -lt 1) {
+    throw "XML validation failed: no '/contentList/content' entries found in '$resolvedXmlPath'."
+}
+
+$seen = [System.Collections.Generic.HashSet[string]]::new()
+foreach ($node in $contentNodes) {
+    $contentUid = [string]$node.GetAttribute("contentuid")
+    if ([string]::IsNullOrWhiteSpace($contentUid)) {
+        throw "XML validation failed: found content node without 'contentuid' in '$resolvedXmlPath'."
+    }
+
+    if (-not $seen.Add($contentUid)) {
+        throw "XML validation failed: duplicate contentuid '$contentUid' in '$resolvedXmlPath'."
+    }
+
+    $version = [string]$node.GetAttribute("version")
+    if ([string]::IsNullOrWhiteSpace($version)) {
+        throw "XML validation failed: contentuid '$contentUid' has empty 'version' in '$resolvedXmlPath'."
+    }
+}
+
+Write-Host "[validate-translation-xml.ps1] XML is valid: '$resolvedXmlPath'. Entries=$($contentNodes.Count)."