orcatongue 1.0.0a1

A tool written in Python to assist with human-driven translation of Minecraft mod(pack)s with a reasonably large number of translation keys.

OrcaTongue

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.

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. 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, including all 132 real languages supported by Minecraft (not including American English), and the 4 'joke' languages.

Roadmap

1.0.0

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

• 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.

• 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.

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

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

• Importing of existing translated language files from sources and placing them in an OrcaTongue format.

• Automatic tracking of outdated translations based on changes in the index file.

• 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 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 for more information.