Skip to content

Bump CI and project to .NET 10; expand README #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ROBdk97 merged 1 commit into from
Mar 19, 2026
Merged

Bump CI and project to .NET 10; expand README #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions .github/workflows/dotnet-desktop.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,13 @@ jobs:
runs-on: windows-latest

steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4

- name: Setup .NET
uses: actions/setup-dotnet@v3
uses: actions/setup-dotnet@v4
with:
dotnet-version: '9.0.x'
dotnet-version: '10.0.x'
cache: true

- name: List Installed Windows SDKs
run: dir 'C:\Program Files (x86)\Windows Kits\10\Lib'
Expand All @@ -41,6 +42,6 @@ jobs:
path: Release.zip

- name: Create GitHub Release
uses: softprops/action-gh-release@v1
uses: softprops/action-gh-release@v2
with:
files: Release.zip
306 changes: 199 additions & 107 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,170 +1,262 @@
# IniTranslator

![GitHub all releases](https://img.shields.io/github/downloads/ROBdk97/IniTranslator/total)

**IniTranslator** is a powerful WPF desktop application designed for easy comparison, editing, and management of INI file translations, commonly used in software localization. With advanced features and an intuitive UI, it simplifies synchronization between English and translated INI files.
IniTranslator is a Windows WPF desktop application for comparing, editing, and maintaining INI-based translations. It helps translators keep English and localized INI files synchronized with side-by-side editing, search and replace, placeholder validation, automatic backups, version comparison, and direct extraction from Star Citizen P4K archives.

![Screenshot](Image.png)

---

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Download Options](#download-options)
- [Build from Source](#build-from-source)
- [Usage](#usage)
- [General Usage](#general-usage)
- [Keyboard Shortcuts](#keyboard-shortcuts)
- [Menu Options](#menu-options)
- [Toolbar Functions](#toolbar-functions)
- [Keyboard Shortcuts](#keyboard-shortcuts)
- [Settings](#settings)
- [Project Structure](#project-structure)
- [Third-Party Components](#third-party-components)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)
- [Repository](#repository)

## Overview

---
IniTranslator is designed for translation maintenance rather than generic text editing.

Typical workflow:

1. Open the current English INI file and the translated INI file.
2. Review entries in a side-by-side editor.
3. Search, filter, replace, or copy source text into translation fields.
4. Translate selected rows with Google Translate or DeepL.
5. Validate placeholders before saving.
6. Save changes with an automatic `.bak` backup of the translated file.
7. Optionally compare against an older English INI or extract a fresh `global.ini` from Star Citizen.

## Features

- **Multi-Language INI File Management**
Open, edit, and compare English and translated INI files side-by-side.

- **INI File Extraction**
Extract INI files directly from *Star Citizen* game files!
- Side-by-side INI editing for source and translated values.
- Fast filtering by key, English text, or translated text.
- Optional regular-expression search and case-insensitive search.
- Batch replace on selected translations.
- Copy/paste support for structured `key=value` clipboard data.
- Copy English source text directly into translation fields.
- Translation of selected rows through Google Translate or DeepL.
- Placeholder mismatch detection for patterns such as `%xx` and Star Citizen action tokens.
- Automatic backup creation when saving translated files.
- Reload backup support from the main UI.
- Comparison against an older INI file to identify changed entries.
- Extraction of `Data/Localization/english/global.ini` from Star Citizen `Data.p4k` archives.
- Built-in P4K archive explorer with search, file export, and directory extraction.
- Light, Dark, and System theme support.
- Persisted window position, size, language, search settings, provider choice, and game path.
- Localized UI with built-in language options:
English, Spanish, French, Italian, Lithuanian, Portuguese (Brazil), and German.

## Requirements

- Windows 10 or later.
- Star Citizen installed locally if you want to use archive extraction or the P4K explorer.
- For source builds: .NET 10 SDK.

Notes:

- The GitHub release package is published as a self-contained `win-x64` build.
- API keys are only required if you want to use machine translation features.

- **P4K Archive Explorer**
Browse, search, and extract files from Star Citizen P4K archives with an intuitive interface.

- **Search & Filtering**
Utilize regex and case-insensitive search to quickly locate entries in large files.
## Installation

- **Placeholder Validation**
Automatically detect and resolve mismatched or missing placeholders.
Download the latest packaged build from GitHub Releases:

- **Backup System**
Create, manage, and restore backups effortlessly.
- [Release.zip](https://github.com/ROBdk97/IniTranslator/releases/latest/download/Release.zip)

- **Translation API Support**
Leverage Google Translate or DeepL APIs for instant translations.
Then:

- **Version Comparison**
Identify differences between current and older INI file versions.
1. Extract the archive.
2. Run `IniTranslator.exe`.

- **Customizable UI**
Switch between Light, Dark, and System themes; save preferences like window size and position.
No separate .NET desktop runtime installation is required for the published release package.

- **Efficient Navigation**
Navigate using intuitive keyboard shortcuts and jump to lines or specific entries with ease.
## Build from Source

- **Comprehensive Editing Tools**
Replace text using regex, copy English values to translation fields, and manage structured clipboard data.
The CI pipeline restores and publishes the WPF application as a self-contained `win-x64` build with .NET 10.

- **File System Integration**
Open INI files directly via Windows Explorer or extract INI files from game archives.
To build locally:

- **Help & Documentation**
In-app guidance with keyboard shortcuts, tooltips, and GitHub repository links.
```powershell
dotnet restore .\IniTranslator\IniTranslator.csproj -r win-x64
dotnet build .\IniTranslator\IniTranslator.csproj -c Release -r win-x64
```

- **Localized Application**
Choose from multiple languages to enhance your experience.
To publish a release-style build locally:

---
```powershell
dotnet publish .\IniTranslator\IniTranslator.csproj -c Release -r win-x64 --no-restore -o publish -p:DebugType=None -p:PublishSingleFile=true --self-contained true
```

## Installation
## Usage

### Prerequisites
### Open and edit translations

- **.NET 8 Desktop Runtime**: Ensure the runtime is installed. The setup file will handle installation if needed.
Use `File > Open` to select:

### Download Options
1. The English source INI file.
2. The translated INI file.

**Direct Executable**
For advanced users who already have the runtime installed.
[Download Executable](https://github.com/ROBdk97/IniTranslator/releases/latest/download/Release.zip)
The main list shows:

---
- Line number
- Key
- English value
- Editable translation value

## Usage
### Search and filter

### General Usage
The toolbar search box filters the current list in real time.

- **Open Files**: Load English and translated INI files via `File > Open` or `Ctrl + O`.
- **Extract from Game**: Retrieve English INI files from *Star Citizen* archives via `File > Extract from Game`.
- **Browse Archives**: Explore P4K archives with the built-in P4K Explorer accessible from the Tools menu.
- **Edit Translations**: Modify translation entries directly in the interface.
- **Translate**: Use the configured API via `Edit > Translate` or `Ctrl + T`.
- **Validate Placeholders**: Locate mismatched placeholders using the toolbar.
- **Save Work**: Save your changes with `Ctrl + S`.
- **Restore Backups**: Reload backups from `File > Load Backup`.
- Search covers key, English text, and translated text.
- `RegEx` enables regular expression matching.
- `Ignore Case` switches between ordinal and case-insensitive matching.
- `Replace` opens a dialog to update selected translations in bulk.

### Keyboard Shortcuts
### Translation helpers

- **Ctrl + O**: Open INI files
- **Ctrl + S**: Save translations
- **Ctrl + T**: Translate selected entries
- **Ctrl + J**: Jump to a specific line
- **F3**: Navigate to the next change
- **F4**: Jump to mismatched placeholders
Editing commands are available from the menu and keyboard shortcuts:

### Menu Options
- Copy selected entries to the clipboard.
- Paste structured `key=value` content back into matching selected rows.
- Copy English text into the translation column.
- Translate selected rows with the configured provider.

#### File
- **Open...**: Load English and translated INI files.
- **Extract from Game**: Retrieve English INI files from *Star Citizen* archives.
- **Save/Reload**: Manage translations.
- **Load Backup**: Restore previous versions.
Currently implemented machine translation providers:

#### Edit
- **Copy/Paste**: Manage clipboard data.
- **Replace**: Find and replace text.
- **Translate**: Automate translations.
- Google Translate
- DeepL

#### Tools
- **Settings**: Configure API keys, themes, and more.
- **Theme**: Toggle between Light, Dark, and System modes.
- **P4K Explorer**: Browse and extract files from Star Citizen game archives.
### Placeholder validation

---
IniTranslator checks placeholders used in the English value against the translated value and helps you jump between mismatches.

## Toolbar Functions
Examples of supported placeholder patterns include:

- **Search**: Filter translations using keywords or regex.
- **Jump to Changes**: Navigate directly to updated translations.
- **Placeholder Validation**: Highlight entries with mismatched placeholders.
- **Progress Indicators**: Monitor tasks in real-time.
- `%s`, `%d`, `%r`
- `[~action(...)]`
- `~action(...)`

---
When mismatches are found, the app warns before saving so you can review them.

## Third-Party Components
### Backups and reload

- This application uses a modified version of [dolkensp/unp4k](https://github.com/dolkensp/unp4k).
- This application uses a modified version of [icsharpcode/SharpZipLib](https://github.com/icsharpcode/SharpZipLib).
- It also relies on `libzstd.dll`.
When you save a translated file, IniTranslator creates a backup next to it:

---
- `yourfile.ini.bak`

## Contributing
You can restore that backup with `File > Load Backup`.

### Compare with an older INI

Use `File > Open Old INI File` to load an earlier English INI version.

This workflow is intended to help when the source file changes between game versions:

- missing keys are added back into the current translation set
- entry ordering is synchronized with the current English file
- changed source entries can be reviewed with the `Jump to Next Change` action

### Extract from Star Citizen

Use `File > Extract from Game` to extract the current English `global.ini` from a selected Star Citizen installation version.

The app attempts to find the game automatically by:

- checking the default installation directory
- falling back to the RSI Launcher log

After selecting a version, IniTranslator reads `Data.p4k`, extracts `Data/Localization/english/global.ini`, and reloads the current translation view against the extracted file.

### P4K archive explorer

We welcome contributions! To contribute:
Use `File > Explore P4K Archive` to open the built-in archive browser.

1. **Fork** the repository.
2. Create a branch: `git checkout -b feature/YourFeatureName`.
3. Commit changes: `git commit -m "Description of changes"`.
4. Push to your branch: `git push origin feature/YourFeatureName`.
5. Open a **Pull Request**.
The explorer supports:

For significant changes, start a discussion by opening an issue.
- loading a Star Citizen `Data.p4k` archive
- browsing directories in a tree view
- searching files by name/path
- viewing basic metadata for the selected item
- exporting individual files
- extracting entire directories

---
CryXmlB files are exported as `.xml` when applicable.

## Keyboard Shortcuts

- `Ctrl+O`: Open English and translated INI files
- `Ctrl+S`: Save translated INI file
- `Ctrl+C`: Copy selected entries
- `Ctrl+V`: Paste clipboard content into selected entries
- `Ctrl+M`: Copy English values into the translation column
- `Ctrl+T`: Translate selected entries
- `Ctrl+J`: Jump to a specific line

Toolbar actions also expose these navigation features:

- Jump to next changed entry
- Jump to next placeholder mismatch

## Settings

The settings window includes:

- UI language
- application theme
- translation provider
- DeepL API key
- Google Translate API key
- Star Citizen installation path

Settings are stored in:

- `%AppData%\ROBdk97\IniTranslator\settings.json`

API keys are stored in the settings file in encrypted form by the application.

## Project Structure

- `IniTranslator/`: main WPF application
- `IniTranslator/ViewModels/`: main editing, settings, help, and P4K explorer logic
- `IniTranslator/Windows/`: dialogs and secondary windows
- `IniTranslator/Helpers/`: settings, translation, file equalization, clipboard, and path helpers
- `IniTranslator/Models/`: settings and translation data models
- `ROBdk97.Unp4k/`: modified P4K archive handling library used by the app
- `IniTranslaterSetup/`: legacy setup project artifacts

## Third-Party Components

- Modified version of [dolkensp/unp4k](https://github.com/dolkensp/unp4k)
- Modified version of [icsharpcode/SharpZipLib](https://github.com/icsharpcode/SharpZipLib)
- [DeepL.net](https://www.nuget.org/packages/DeepL.net)
- `libzstd.dll` / Zstandard support used by the archive tooling

## Contributing

Contributions are welcome.

1. Fork the repository.
2. Create a branch for your change.
3. Make and test the change.
4. Open a pull request with a clear description.

If you plan a larger change, open an issue first so the scope can be discussed.

## License

This project is licensed under the [MIT License](https://github.com/ROBdk97/IniTranslator/blob/main/LICENSE).

---

## Contact
## Repository

- **GitHub Repository**: [IniTranslator](https://github.com/ROBdk97/IniTranslator)
- **Issues & Feature Requests**: Open an issue on GitHub
- GitHub: [ROBdk97/IniTranslator](https://github.com/ROBdk97/IniTranslator)
- Issues: [Open an issue](https://github.com/ROBdk97/IniTranslator/issues)
Loading
Loading