@dymerz/starcitizen-ini-utils NPM

StarCitizen INI Utils

Overview

@dymerz/starcitizen-ini-utils is a specialized utility tool designed for working with Star Citizen localization files in INI format. This tool offers commands to validate and merge INI files, making it easier to manage and maintain localization data.

Key Features

Validation: Check if all entries from a reference file exist in source files and verify placeholder consistency
Merging: Combine multiple INI files intelligently to create updated localization files
Placeholder Validation: Ensures that special placeholders (% and ~ format) match between reference and translated content
CI/CD Integration: Can be used in continuous integration workflows with the --ci flag

Prerequisites

Node.js (version 18 or higher)
npm

Installation Options

Option 1: Use directly with npx (No Installation Required)

The easiest way to use this tool is directly with npx:

npx @dymerz/starcitizen-ini-utils

Option 2: Install as a project dependency

npm install @dymerz/starcitizen-ini-utils --save-dev

Option 3: Local development setup

Clone the repository:

git clone https://github.com/Dymerz/StarCitizen-Localization.git
cd tools/ini-utils

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Run tests:
```
npm test
```

Usage

Command: `validate`

Verifies that all entries from a reference INI file are present in the source files and checks that the placeholders match properly.

npx @dymerz/starcitizen-ini-utils validate <files...> [options]

Parameters:

<files...>: Paths to the INI files to validate

Options:

Option	Description	Default
`--reference-type <type>`	Type of reference: "github" or "local"	"github"
`--github-branch <branch>`	GitHub branch to use as reference (main, ptu, etc.)	"main"
`--github-repository <repo>`	GitHub repository path	"Dymerz/StarCitizen-Localization"
`--github-file-path <path>`	Path to file within repository	"data/Localization/english/global.ini"
`--local-path <path>`	Path to local reference file	(required when reference-type is "local")
`--ci`	Run in CI mode with machine-readable output format and GitHub Actions annotations	false
`--fail-on-error`	Exit with code 1 when validation errors are found	false

CI Mode Features

When running with the --ci flag:

Uses machine-readable output format optimized for CI environments
Generates GitHub Actions compatible annotations (::error:: and ::notice::)
Groups output for better readability in GitHub Actions logs
Returns non-zero exit code (1) when validation fails
Provides concise error summaries at the end of execution

Examples:

# Validate against main branch on GitHub (default)
npx @dymerz/starcitizen-ini-utils validate ../../data/Localization/german_(germany)/global.ini

# Validate against PTU branch
npx @dymerz/starcitizen-ini-utils validate ../../data/Localization/german_(germany)/global.ini --github-branch ptu

# Validate against local reference file
npx @dymerz/starcitizen-ini-utils validate ../../data/Localization/german_(germany)/global.ini \
  --reference-type local --local-path ../../data/Localization/english/global.ini

# Run in CI mode with GitHub Actions annotations
npx @dymerz/starcitizen-ini-utils validate ../../data/Localization/**/global.ini \
  --reference-type local \
  --local-path ../../data/Localization/english/global.ini \
  --ci

# Run validation and exit with error code if validation fails
npx @dymerz/starcitizen-ini-utils validate ../../data/Localization/french_(france)/global.ini \
  --fail-on-error

Command: `merge`

Merges multiple INI files, taking values from files in order of priority, and saves the result to a new file.

npx @dymerz/starcitizen-ini-utils merge <referenceFilePath> <sourceFilePath> <replacementFilePath> <outputFilePath>

Parameters:

<referenceFilePath>: Path to the reference INI file (provides the structure and fallback values)
<sourceFilePath>: Path to the source INI file (first priority for values)
<replacementFilePath>: Path to the replacement INI file (second priority for values)
<outputFilePath>: Path to save the merged INI file

Example:

npx @dymerz/starcitizen-ini-utils merge \
  ./english/global.ini \
  ./french_old/global.ini \
  ./french_updates/global.ini \
  ./french_merged/global.ini

Technical Details

Written in TypeScript with strong typing
Creates UTF-8 files with BOM (Byte Order Mark) for proper encoding
Handles special characters in INI files by properly escaping semicolons and hash symbols
Validates both percent placeholders (%name) and tilde placeholders (~name(parameter))
Supports case-insensitive placeholder validation