Metadata-Version: 2.4
Name: orcatongue
Version: 1.0.0a1
Summary: A tool written in Python to assist with human-driven translation of Minecraft mod(pack)s with a reasonably large number of translation keys.
Keywords: translation,minecraft,modpack,mod,resource pack,i18n,internationalisation,internationalization,l10n,localisation,localization
Author: The-Shortman
License-Expression: MIT
Classifier: Development Status :: 1 - Planning
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Internationalization
Requires-Dist: gitpython>=3.1.46
Requires-Dist: rich>=15.0.0
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: typer>=0.24.1
Requires-Python: >=3.14
Project-URL: Repository, https://codeberg.org/The-Shortman/OrcaTongue
Project-URL: Issues, https://codeberg.org/The-Shortman/OrcaTongue/issues
Project-URL: Changelog, https://codeberg.org/The-Shortman/OrcaTongue/src/branch/main/CHANGELOG.md
Description-Content-Type: text/markdown

<div align="center">
  <h1>OrcaTongue</h1>
	<br />
	<img src="https://codeberg.org/The-Shortman/OrcaTongue/raw/branch/main/icon.png">
	<br />
	<b>A command-line tool written in Python to assist with human-driven translation of Minecraft mods, modpacks, and resource packs, with a reasonably large number of translation keys.</b>
</div>
<br />

This tool is originally written as a first-party solution for use by the Create: Astral translation contributors, to concentrate all translation efforts into one repository, assess which languages are outdated, how much of each language is translated, and to automatically flag any issues.

This repository contains the source code in the `src/` directory. The source code is licensed under the [MIT License](https://codeberg.org/The-Shortman/OrcaTongue/LICENSE). Feel free to fork this repository for your own needs, as long as you follow the terms set out by the licence.

## Features

### Git-powered source management

OrcaTongue uses Git to pull translation sources from remote repositories, meaning it can be run from anywhere Git is installed, with maximum compatibility across public Git hosting providers, such as Codeberg/Forgejo, GitHub, Gitlab, and more, without having to manually import translation files.

Developers can specify the Git HTTPS URL, ref, and a specific folder location to pull language files from, providing fine control and allowing minimisation of bandwidth requirements.

American English (en_us) files are automatically indexed from provided sources, and updated by simply running the `orcatongue index` command.

### Multi-source support

One repository, multiple translation projects. Concentrate the effort of community translations in one place for all of your mods, modpacks, and resource packs, minimising friction and maximising contributions.

### Tracking for outdated and incomplete translations

OrcaTongue automatically compares differences in your en_us files to identify and track phrases that have been changed, meaning translators spend less time skimming Git diffs, and more time trying to figure out a suitable replacement for that pun that only works in English.

### Support for 136 languages out of the box; built specifically for Minecraft projects

OrcaTongue has support for all 136 languages on the [minecraft.wiki article](https://minecraft.wiki/w/Language), including all 132 real languages supported by Minecraft (not including American English), and the 4 'joke' languages.

## Roadmap

### 1.0.0

- [x] Project metadata management via a JSON file, storing: project name, OrcaTongue version, groups (and their sources), and languages.

- [x] Source management, including adding, removing, and listing sources from the command line. Sources are pulled from a remote repository using git archive, allowing fine control over sources per-repository that are to be translated, and reducing bandwidth requirements, especially when pulling from large monolithic repositories.

- [x] Project indexing with support for standard Minecraft lang file syntax, scraping sources for en_us.json files and recording the language keys and their values in an index JSON file.

- [x] Group management, allowing multiple individual projects to have different translation scopes in a single OrcaTongue-enabled repository.

- [x] Language management via the command line, allowing selective languages to be managed based on the community's needs.

- [x] Importing of existing translated language files from sources and placing them in an OrcaTongue format.

- [x] Automatic tracking of outdated translations based on changes in the index file.

- [x] Exporting of translations to Minecraft-readable JSON syntax.

- [ ] A human-friendly frontend that can, at the very least, interface with the languages in group-specific indexes in a focused manner.

### 1.1.0

- [ ] Automatically show a "percentage translated" status bar, accessible via an API or shown through the project's README file, or similar.

- [ ] Add support for FancyMenu-syntax localisation files.

## Installation

OrcaTongue currently does not have any convenient way to install, unless you build from source using `uv build`.

This will change once the tool is released as version `1.0.0`.

## Documentation

Documentation for OrcaTongue can be found at the official repository Wiki: https://codeberg.org/The-Shortman/OrcaTongue/wiki

## Contribution

OrcaTongue uses [uv](https://docs.astral.sh/uv/) to build the project and manage dependencies. Ensure you have `uv` installed, clone this repository, and run `uv sync` in your local repository to set up a virtual environment and install OrcaTongue's dependencies.

Ensure that you run your commands while the virtual environment is active to prevent dependency conflicts. See [here](https://docs.astral.sh/uv/concepts/projects/layout/#the-project-environment) for more information.