Contributing

From Era Wiki
Revision as of 15:39, 20 November 2023 by Strmesko (talk | contribs) (Translation Tools)
Jump to: navigation, search

Overview

Make sure the clipboard settings look like above for Chiitrans and TA to work.

The era translation group lacks organization by design as it removes nearly all overhead. How each game is translated depends on the maintainer, but generally five tools are used.

Git
Git is a revision control software that lets people work on one or more files at the same time without having to deal with manually merging the changes.
Text editor
A program for editing text on a more advanced level than Notepad. Desired features include searching all open files, searching via REGEX etc.
Diffing tool
A dedicated non-git tool for comparing two or more files.
Shift-jis converter
Some text editors and Git clients cannot handle shift-jis very well, and converting them manually to UTF-8-BOM is unpractical.
Translation tools
For understanding Japanese.

Details about each section follows.

Git

Git revolves around repositories, with the point being that it should be possible to know exactly when a particular line in a file was modified. By viewing changes and updates on a line-by-line basis, it becomes possible for several people to work on a file without having to communicate with the others exactly what they are doing.
Here are some common terms that will be used when working with git:

Repository
A self-contained project. A repository contains every state of a project at once.
Branch
A state of a project with its own diverging history. It is easy to move from one branch to another, and to merge them.
Merge
Merging is when the accumulated changes in one branch is applied to another. It only applies the changes not present.
Merge conflict
The result of two parallel commits changing one line, this requires human intervention.
Clone
The act of copying a repository while still maintaining references to it, so that changes applied to one can be applied to the other as well.
Remote
The repository a clone links to. Typically hosted online.
Unstaged
Pure line-by-line changes with no distinction.
Staged
An explicitly selected change.
Commit
A set of changes, typically along with a descriptive message. All staged changes are added to a commit when it is created.
Push
This sends all unsent commits to the remote repository.
Pull
This retrieves all new commits from the remote repository and merges them into the local state.
Collaborator
Someone with write access to a repository.
Maintainer
Someone in charge of handling and managing one or more repositories.


The current Git repositories are located here.
Git can be used either via the command line or through clients. The recommended one is GitKraken.

If you don't know how to use Git, check out Learn Git Branching and Think Like (a) Git.

Text Editor

There are myriad of text editors available, but the one suggested by this guide is Visual Studio Code. (Note: Not just Visual Studio, but Visual Studio Code.)
Three plugins are recommended.

  • Code Spell Checker - Useful for finding spelling errors.
  • EraBasic - For getting highlighted text and the ability to jump to where functions are defined.
  • GitLens — Git supercharged - Uses the .git folder in the game directory to tell which commit made which line, as it is done automatically it does not require linking the program to Git.

Diffing Tool

Git will only merge updates not already merged. Because of this external tools are needed to compare things larger in scope, for instance entire games.
The recommended one is KDiff3. It can be linked to GitKraken but that is not recommended as it requires further tweaking.

Shift-jis Converter

Depending on the Emuera version used, era can only run files with certain encodings, two of them being Shift JIS and the other being UTF-8 BOM. The difference is that some programs like GitKraken and node.js (Visual Studio Code uses that for searching unopened files) cannot decode Shift JIS. Because of this games are converted to UTF-8 BOM in most cases instead.
There are three methods.

  • EraEncodingConverter - C# program that can convert file line endings and encoding (UTF-8 by default). Has compiled executables for Windows, MacOS and Linux and a Python 3 version that has less features but can autodetect encodings for converting.
  • SHIFTJIS-B-Gone - Python 3 script used with the command line.
  • ShiftJisFuckOff - Pre-compiled c# executable used by dropping a folder on top of it. It is easier to use than the above one but might be incompatible with anything that is not Windows.
  • Manually converting it using a text editor - As the process has to be done file-by-file it is not recommended. It does have merits though in case the above two fail.

Short authorization guide in gitgud account when using Visual studio Code

Translation Tools

A quick guide to MTL. Translation Aggregator (left) and ChiiTrans (right)

To translate games, often more than one program is used as Japanese and English are very far apart in terms of grammar and vocabulary. Most use the clipboard to read input, meaning copied text is instantly transfered and translated to the output window.

  • Translation Aggregator - Aggregator for translation services including Google, Bing, Yandex etc.
  • Chiitrans Lite - Has a benefit over Translation Aggregator by linking up against jisho and getting the definitions of words that way.
  • ATLAS v14 - Offline dictionary for use by Chiitrans Lite or Translation Aggregator. Unfortunately installation is doing though MSI app which prevents it from install in windows 10
Note on translating

This will need an entire page for itself, but here are a few pointers about machine translation.

  • Never trust anything Just because Google Translate says something that does not make it true. This might be good enough for playing but not for translating. It is often impossible to map anything between English and Japanese 1-to-1. Some concepts and words might mean different things, several things, or might not exist.


  • Learn the grammar If studied an hour per day it will take about a week or so to get to levels where Chiitrans Lite becomes helpful. Once the sentences are reduced to particles, verbs, nouns, and adjectives, translation will be easier.


  • Learn hiragana and katakana Coming across "ローター" in the code and having to look that up takes time, with just katakana it becomes "rootaa" instead - rotor. Learning hiragana makes it easier to tell sentences apart at a glance - it goes from scribbles to something recognized if not known.


  • Never use search and replace Just avoid it entirely, it is a dangerous tool that more easily does harm than good.


  • Learn the Text Editor This involves selecting multiple lines, using REGEX, and other particularities of the program.


For a more complete guide, go here [Computer-assisted translation].

Workflow

Current workflow all games are encouraged to follow.

Here the complete workflow is described, from Japanese updates to English releases. First each branch is described.

game/japanese

Japanese games are released in three versions, standalone, character dialog, and patches. Unless there has been a considerable amount of time since the last standalone - months or years - the latter two are ignored. Standalone versions contain everything required to run the game, and the latest standalone version of a game can be found in the game/japanese branch of that game.

game/japanese-utf-8

If the game is not in UTF-8 BOM from the start it is converted and put in the game/japanese-utf-8 branch manually. The game/japanese-utf-8 branch should never be merged into another branch, nor should any branch merge into it.

game/eng-translation

Initially a branch of game/japanese-utf-8, and should optimally contain as few modifications as possible, preferably only the text itself. Additions are not a big problem but should be commented, while removing something warrants a good reason. If something is needed for the game to make sense in English, it naturally goes here.
They should contain a changelog with entries based on commits describing what has been done.

feature/*

To change the game in ways other than pure text, feature branches are made. They are all branched off game/eng-translation and sit there self-contained until merged into eng-development. They should contain a readme or changelog describing what the feature does, how, and where.

game/eng-development

Whenever a new update to game/eng-translation is made or a feature branch is in a ready state, they get merged into game/eng-development. But the branch itself should not contain original changes.

game/release

When game/eng-development has been stable for a while the contents game/release is replaced with that of game/eng-development. The history of this branch should not contain any other branch.

To autogenerate release notes, use this command:

git shortlog [previous release tag]...[current release tag] --format="%h%x09%s" --no-merges

(Ex.

git shortlog ANON_4.891_17-04-23...ANON_4.900_31-05-23 --format="%h%x09%s" --no-merges


Japanese updates

When Japanese updates are released game/japanese and game/japanese-utf-8 are updated as listed above. Then game/japanese-utf-8 is diffed with tool into game/eng-translation. It it because tools often lack git integration that game/eng-translation should contain as few differences as possible.

Tips:

  • Having a git client open to see which files and lines have been changed in game/japanese-utf-8 makes it easier to avoid diffing unnecessary files.
  • Using comments like ";Custom code" also makes it clearer when to not overwrite code.
  • Keeping a changelog of all new things helps, and doing that when diffing is easy.

After the game/eng-translation has been updated it is time to update game/eng-development. The problem here is that some feature branches might contradict what the update just added. To avoid having to care about backward compatibility game/eng-development is simply deleted. A new game/eng-development is then created by branching game/eng-translation and applying the feature branches to that.
Should any merge conflict emerge then it can be fixed in game/eng-development if it is minor, but it would be better to fix it in the feature branch itself.


External Links

  • eralang — Basics on the programming language behind era games. Recommended to take a look at if it's your first time working with era.
  • GitKraken — Explains how to set up GitKraken properly with the eragames repository.


Setting up a new project

The Japanese uploads are here for touhou and here for other things. Account for both is era/era. It is there that new games are found.
Generally, Namanicha will add whatever new games are uploaded to the Git, so making new projects does not make sense.

Contributing to an ongoing project

Begin by reading the above to understand what the process entails. Then ask in the discord.

Contributing to specific games

eraTohoTW: Contributing/Modding TW