Metadata-Version: 2.4
Name: strindex
Version: 5.0.1
Summary: A command line utility that allows you to easily extract, list and patch the strings embedded in a few filetypes.
Author-email: zWolfrost <zwolfrost@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/zWolfrost/strindex
Keywords: PE,strings,patching,translation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ahocorasick_rs>=1.0.0
Requires-Dist: pefile>=2024.8.26
Provides-Extra: lang
Requires-Dist: lingua-language-detector==2.*; extra == "lang"
Requires-Dist: language-tool-python==3.*; extra == "lang"
Provides-Extra: gui
Requires-Dist: pyside6==6.*; extra == "gui"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: Nuitka==4.*; extra == "dev"
Requires-Dist: imageio==2.*; sys_platform == "win32" and extra == "dev"
Requires-Dist: pytest==9.*; extra == "dev"
Dynamic: license-file

# strindex
[![PyPI version](https://img.shields.io/pypi/v/strindex?label=PyPI%20version)](https://pypi.org/project/strindex/)
[![GitHub downloads](https://img.shields.io/github/downloads/zWolfrost/strindex/total?label=GitHub%20downloads)](https://github.com/zWolfrost/strindex/releases/latest)
[![license](https://img.shields.io/github/license/zWolfrost/strindex)](LICENSE)

A command line utility program (with GUI support) that allows you to easily extract, list and patch (replace) the strings embedded in a few filetypes.

It's useful to change the text of a binary file without having to recompile it; for example, to translate it into another language.

A string can be referenced not only by its pointer / offset, but also by the original string itself to ensure compatibility with different versions of the same program.

It features various built-in features to help with translation, such as spellchecking & filtering strings by length and character set.

## Supported filetypes
*Support for more filetypes is possible, but not planned*

- PE files (".exe", ".dll"...) *(direct pointers only!)*
- Gamemaker data files ("data.win")
- Unreal Engine localization files (".locres")
- Every filetype, if using force mode*...

**Force mode doesn't allow the replaced strings to be bigger in length than the original strings.*

## Installation
You can install the program with the command `pip install strindex`.

Alternatively, the [releases tab](https://github.com/zWolfrost/strindex/releases/latest) includes a precompiled version of the program, which by default opens in gui mode (unless executed with arguments). Warning: the precompiled version has a high chance of being detected as a **false positive** by antivirus software. You can compile the program yourself to avoid this.

## Usage
You can run the program with the command `strindex <action> <input file(s)> [arguments]`.

`strindex -h` will show more information about the available actions and arguments.

*Most notably*, the program supports the following actions:
- `create`: Create a list of string replacement instructions (a strindex) extracted from a binary file. Use `-f` to enable "force" mode, and replace strings at the same offset they were found. Use `-D` to create a strindex that uses the original strings as references (dynamic pointers), instead of offsets (fixed pointers).
- `patch`: Patch a binary file using a strindex. Strindex files compressed with gzip are also supported for all actions.
- `gui`: Open Strindex in GUI mode.

## Usage Examples
- Open strindex in GUI mode:
  ```sh
  strindex gui
  ```
- Create a strindex from a PE file, considering only pointers prefixed by the bytes "24c7442404" or "ec04c70424".
  ```sh
  strindex create program.exe -p "24c7442404" -p "ec04c70424"
  ```
- Patch a PE file with a strindex:
  ```sh
  strindex patch program.exe strindex.txt
  ```

## Strindex Example
You can find an example of a strindex file and an explanation of its settings [here](strindex_example.txt).

## Verified programs/videogames
Here is a *non-exhaustive* list of programs/videogames that have been verified to work with strindex:

| Name                                                               | File name & type         | Notes
|--------------------------------------------------------------------|--------------------------|-------
| [**Katana ZERO**](https://store.steampowered.com/app/460950)       | `Katana ZERO.exe` (PE)   |
| [**Nuclear Throne**](https://store.steampowered.com/app/242680)    | `nuclearthrone.exe` (PE) | *
| [**Persona 4 Golden**](https://store.steampowered.com/app/1113000) | `P4G.exe` (PE)           | Notably, the only text that is embedded in this game's .exe file are cutscene subtitles.
| [**Undertale**](https://store.steampowered.com/app/391540)         | `data.win` (IFF)         |
| [**MOLE**](https://store.steampowered.com/app/4064510)             | `Game.locres` (locres)   | `Game.locres` is "packed" in `Mole-Windows.pak` (which must be extracted first, using a tool like [repak](https://github.com/trumank/repak)).

*This program/videogame already officially supports localization by external means.
