Docs

Overview API FAQ Service Install

FAQ

What is ZTranslate? How does it work?:

ZTranslate is a program to translate video games and display that translation realtime. Run the ZTranslate client, and load the translation package for the game, and then run the game. With the ZTranslate client running in the background, it will grab a screenshot of the in-focus window (in this case, the game), and then use the package to determine where the text is, and what the translation should be. It then updates the ZTranslate window with the translated text written over the grab screenshot. It will do this continuously.



Why not just modify the executables with the translation instead?

There are a few reasons for this approach. The first is accessibility. Allowing translators to avoid having to do hex editing, and adding helpful functionality (like suggested machine translations, and a contextual screenshot) makes the translation process a lot faster. Second, the approach can do things simple hex editing can't do, like translate text stored in an image, add translated subtitles for audio, and give translations for games that can't be hex edited at all (for example, many console games).


Besides that, hex editing can be difficult if the game uses strange compression or encodings for the strings, or it may be difficult to change the length of the translated string inside the .exe (for example, how do you translate "Pilz" into "Mushroom" if you can only use 4 characters?).



It's not translating my screen when I press (~), what's wrong?

It's likey that either your config file doesn't have your API key in it, or the client is having issues with the graphic driver.

In the ztranslate folder on your computer, open the "config.json" file with some kind of text editor (eg: Notepad, Wordpad, etc.). Then, log into your ztranslate.net account and go to the settings page. On the bottom, there's a API key listed. Copy and paste it into the "user_api_key" field and restart the ztranslate client.

If you're getting black screens back in your ztranslate window, then it's likely a driver issue. For some games, this may not be as easy to fix, but many games will have display drivers. Try different drivers and see if they'll work instead.


How do I make a translation myself?

There are two steps to making a translation: sourcing the images, and fixing the translations. To source images, first log into ztranslate.net, go to the settings link and copy the API key given. In your ZTranlate client folder, edit the config.json file and paste the API key into the value of the user_api_key field. Now, run the ZTranslate client in the background and do not load a package. When you press "~", it will grab a screenshot of the window in focus, send the image to the ztranslate.net server and display an automatic translation (this may take a few seconds). Do this for all the visible text in the game, or as much as you can handle.


Next, go to the Game List link on ztranslate.net and create a game page. Edit the new game's page and modify the game name and so on, and create some indexes for the game (see Indexes under the docs section). Now, go to the "Edit Game" link for the "(uncategorized)" game in the game list (this is where newly sourced images are sent to), and move these images to your newly created game.


Now it's time for the second step and fix those translations. Click on the game's name on the Game List page, and click on the first image. The left image shows the text box areas highlighted, while the right image is (for now) just the same image. Fix mistranslated text, and add new textboxes that weren't found in the sourcing step, and submit your changes. The easiest way to change a textbox's bounding box is to click on the left image, hold and drag, and then release the mouse button. The x,y,w,h of the rectangle drawn by this will be shown below the images and clicking "Copy Box" on the translation line will copy its value to this bounding box. With the translation updated and submitted, click on the "Index Image" link at the top of the page. When it returns, the translated image (as it would be translated by the ZTranslate client) will be shown on the right. Repeat this process on all the images.


Now, to download the package file, go to the Image List page for the game, and click "Download Package" and you're done. For more information on how to create indexes, and other features, see the Docs page.



How well do I need to know a foreign language to translate? What if I don't know another language myself?

For the translation, it is more important to know the target language than the original source language. Knowing the original language's grammar may be enough to do a translation, while you use dictionaries to check up words. This is especially true between widely used languages in the same language family (eg: Indo-European), since machine translation can do a lot of the work. For something like Japanese to English, better knowledge of Japanese would help since the machine translation will have more difficulties.


Still, even if you don't know any foreign language yourself, you can help by doing the sourcing step for others. Source a game in your language, and share the game with someone else, who can finish a translation.



Why have translators at all? Why not just make everything automated?

Besides the fact that OCR and machine translation at times is not that accurate or fast, translation itself is a creative art. Literal transations are not as good as figuartive ones, and figurative translations are not as good as contextual ones. When translating german humor into english, or translating a twenty year old game, the context of the game can change. Things that make sense in one culture at one time can be different in a different one.


By not forcing a translation to be literal, the translator can create a better experience for the player. This could be by explaining a puzzle better, steering players to avoid bugs, or even poking fun of a cliche the game is using.


Still, if you just want a machine translation, you can just do the sourcing step by itself, which will show the ocr and translation as you play. It'll be slower, and you may only get the gist of what's being said, but it should be a lot easier than spending years to learn another language.



What is OCR?

OCR stands for Optical Character Recognition. This is any algorithm that takes an image and outputs where and what the written text is inside that image. OCR is used at two points with ZTranslate: the sourcing step to get a sample translation, and at the indexing step for the client to quickly get a translation from the package. Using OCR in the indexing step has some advantages, in that it will work with text that moves, or may be at different spots on the screen when it comes up (in contrast to the difference algorithm which requires the text to be stationary), or with text that changes but follows a pattern (for example: "I currently have 120 gold pieces").


Unfortunately, OCR has its drawbacks too. It's a slower algorithm, requires a lot of pre-processing on the image for it to properly return the text, and needs to use trained data (english and german datasets are included in the client package). This is explained more in the docs.



Why is there a Quota listed?

For the sourcing step, the ztranslate.net server does an API call to Google to OCR the text and another to translate the text. This costs about $1.50 per 1,000 calls. So, to source a game that needs 10,000 screenshots would cost about $30. The quota system is there to limit the total number of these API calls so I don't go broke. Maybe I could add some ads instead, take donations, or figure out a better way of doing that sourcing for free.


The benefits of using Google's OCR API is that it does work well for general images. Usually OCR requires a lot of preprocessing to get the image down to white text on a clear back background, or vice versa, but their api can try a lot of different preprocessing algorithms to try and find the text. The downside though is that it can take a lot of time to process a single image, especially if there is no text on the screen. It can also include false positives as well, like returning "XXXxX XX" where a chain-link fence is. Still, for what it does, it's a very useful time saver.


Still, if you go over your quota (or switch your client to free mode), the images you source from the client will be saved, so you can still translate them. However, you would have to select the textboxes, and transcribe/translate the text yourself.