Dalamud Excel Language Packs

Reproducible generation and publication of the managed English Excel overlay used by China Dalamud. This repository stores the profile, schemas, builder, and scripts. The validated manifest and pack are committed to DalamudAssets/cn, where the existing Assets rehash and cache-refresh chain distributes them.

Current scope

The initial release contains only en-lite. It lets plugins using Dalamud's shared Lumina instance read common Sheets with Language.English while the client, fonts, and all native game Excel requests remain Simplified Chinese.

The source is the public en and chs SaintCoinach CSV snapshot in InfSein/ffxiv-datamining-mixed. The pipeline reads the exact game version from the latest EN and CHS commit bodies and refuses to build until they match.

The source repository does not currently declare a redistribution license. Public readability is not publication authorization; keep the protected publish environment disabled until the operator has confirmed the required rights or permission.

CSV exports cannot reproduce original SeString macro bytes. The .xlcsvpack format therefore contains non-empty ordinary English UTF-8 string cells plus only those macro-bearing cells that the producer can convert to canonical Lumina macro strings and compile strictly. At runtime Dalamud clones the matching China Sheet, replaces those cells, and preserves all numbers, references, unsupported macro strings, empty-source cells, and unselected Sheets from the China client. This is a managed-only compatibility layer:

• IDataManager and plugins using Dalamud's shared GameData.Excel can read it.
• Plugins opening their own game installation cannot.
• It cannot activate the native Excel language bridge or switch the game UI language.
• A future raw EXH/EXD source can reuse the profile, catalog, immutable publication, and Assets synchronization without treating this overlay as native-compatible.

Pack contract

language-pack.json remains manifest format 2 with:

source = csv-overlay
targetCompatibilityValidated = false
path = en-lite.xlcsvpack

The ZIP-based overlay remains format version 1. pack.json binds the exact game version, language, profile, sheet list, variants, and physical column types. Each Sheet keeps the original rows array and (column, value) UTF-8 cell shape. Sheets may additionally contain macroRows with the same row/cell shape; older Core versions ignore that unknown property and continue applying rows, while macro-aware Core versions compile only macroRows values before writing EXDF bytes.

The trusted producer converts the reversible SaintCoinach CSV representation before writing the pack. The accepted source grammar is limited to UIForeground, UIGlow, and nested If/Else using the observed Equal or GreaterThanOrEqualTo player-parameter conditions. It strictly compiles the converted value, stores ToMacroString() output in macroRows, and verifies a strict canonical round-trip. The verifier repeats only the Lumina compile/canonical checks. Macro cells outside the source grammar are omitted and remain Chinese at runtime. A row/column may occur in only one of rows or macroRows.

profiles/lite.json is the versioned allowlist. The effective profile hash uses the sorted set of Sheets that are present and compatible in both EN and CHS snapshots. Subrow Sheets and Sheets with no safely encodable English cells are skipped and reported.

Local build

Requirements: PowerShell 7, Git, and .NET 10.

git clone --filter=blob:none --sparse https://github.com/InfSein/ffxiv-datamining-mixed.git .\vendor\datamining
git -C .\vendor\datamining sparse-checkout set en chs

.\tests\Run-SelfTest.ps1
.\scripts\Build-All.ps1 `
    -DataminingRepository .\vendor\datamining `
    -OutputRoot .\artifacts

.\scripts\New-Catalog.ps1 `
    -ArtifactRoot .\artifacts `
    -CdnBaseUrl https://s3.ffxiv.wang/language-packs `
    -OutputPath .\artifacts\catalog.json

.\scripts\Test-Artifacts.ps1 `
    -ArtifactRoot .\artifacts `
    -CatalogPath .\artifacts\catalog.json

Generated artifacts are ignored in this repository. The validated language-pack.json and en-lite.xlcsvpack are embedded in DalamudAssets.

Workflow and publication

The review workflow runs on windows-latest; no game installation or self-hosted runner is required. It checks out only en and chs, builds and reopens the overlay, generates a catalog, runs a zero-upload publication preflight, and retains review artifacts.

DalamudAssets/.github/workflows/en-lite.yml runs the same build on a schedule and on manual dispatch. Because this repository is public, the Assets workflow can check it out without a cross-repository token, then use its own scoped GITHUB_TOKEN to commit only when the validated manifest or pack changed.

Assets publication order:

1. Reopen and validate the complete local overlay, manifest, profile, catalog, hashes, and provenance.
2. Copy language-pack.json and en-lite.xlcsvpack to UIRes/ExcelLanguagePacks/en-lite.
3. Replace the two matching asset.json entries with raw GitHub URLs and verified SHA-1 hashes.
4. Increment the Assets version and push only when content changed.
5. Let the existing Rehash Assets workflow verify hashes and clear the Web Services cache.

Repository layout

Path	Purpose
config/release-matrix.json	Initial one-pack release contract
profiles/lite.json	Deterministic Sheet allowlist
tools/DataminingOverlayPackBuilder/	CSV parser, deterministic pack writer, and strict verifier
schemas/, examples/	Manifest, profile, and catalog contracts
scripts/Build-All.ps1	Snapshot/version resolution and en-lite build
scripts/Test-Artifacts.ps1	Complete local publication preflight
scripts/Publish-S3.ps1	Optional immutable S3 publisher for future larger packs
scripts/Update-CatalogBranch.ps1	Optional catalog branch updater
scripts/Update-DalamudAssets.ps1	Embed and publish en-lite through DalamudAssets
tests/Run-SelfTest.ps1	Repository contract and failure-path tests