From bf07261311060819a04bfbc76512fb3a3496fbe6 Mon Sep 17 00:00:00 2001 From: ROBdk97 Date: Thu, 19 Mar 2026 10:21:57 +0100 Subject: [PATCH] Bump CI and project to .NET 10; expand README Update GitHub Actions workflow to use actions/checkout@v4, actions/setup-dotnet@v4 and target .NET 10 (dotnet-version: 10.0.x) with caching enabled; also update softprops/action-gh-release to v2. Change ROBdk97.Unp4k project target framework from net9.0 to net10.0. Substantially expand and reorganize README: add Overview, Requirements, Build-from-source and Usage sections, document build/publish commands for self-contained win-x64 builds, enumerate features, keyboard shortcuts, P4K explorer/backup behavior, and update release/download guidance. These changes align CI and the project with .NET 10 and improve end-user and developer documentation. --- .github/workflows/dotnet-desktop.yml | 9 +- README.md | 306 +++++++++++++++++---------- ROBdk97.Unp4k/ROBdk97.Unp4k.csproj | 2 +- 3 files changed, 205 insertions(+), 112 deletions(-) diff --git a/.github/workflows/dotnet-desktop.yml b/.github/workflows/dotnet-desktop.yml index 7a98d36..857800c 100644 --- a/.github/workflows/dotnet-desktop.yml +++ b/.github/workflows/dotnet-desktop.yml @@ -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' @@ -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 diff --git a/README.md b/README.md index 387853d..82571e4 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/ROBdk97.Unp4k/ROBdk97.Unp4k.csproj b/ROBdk97.Unp4k/ROBdk97.Unp4k.csproj index 5748257..fa29399 100644 --- a/ROBdk97.Unp4k/ROBdk97.Unp4k.csproj +++ b/ROBdk97.Unp4k/ROBdk97.Unp4k.csproj @@ -1,6 +1,6 @@  - net9.0 + net10.0 enable enable AnyCPU;x64