Localization - Translate your project into several languages

[DK]

Author: DKPlugins
Version: 1.4.6
Description: Localization of game. Translate your project into several languages.

Requirements and dependencies:

1. Availability of working plugin DKTools version 1.3.5 or above

Features:

1. Unlimited number of languages
2. Ability to use different audio/image resources for different languages
3. Use the tags {} to localize a text
4. The text localization is stored in the locales folder
5. Unlimited number of localization files
6. Works on all platforms! PC, mobile phones, browsers!
7. You can translate any parameters of other plugins
8. Saving untranslated tags to a separate file using the plugin command will help you not to forget about something important
9. 2 customizable language selection screens
10. Change the language through options, title screen
11. No need to restart the game to change the language. Everything changes instantly
12. Use different fonts for different languages

Screenshots:

Spoiler: screenshots

How to add the option to VisuMZ_1_OptionsCore:

Spoiler: VisuMZ_1_OptionsCore

1. Place VisuMZ_1_OptionsCore plugin ABOVE in the plugin list
2. Enable "Show Options Command" parameter in the Localization plugin
3. Configure the new option in VisuMZ_1_OptionsCore.js with following parameters:
Symbol: locale
JS: Text:
return LocalizationParam.get('Options Command Name');
JS: Show/Hide:
return Imported['DKTools_Localization'] && LocalizationParam.get('Show Options Command');
JS: Draw Option:
const index = arguments[1];
const title = this.commandName(index);
const rect = this.itemLineRect(index);
const halfWidth = rect.width / 2;

this.resetFontSettings();
this.changePaintOpacity(true);
this.drawTextEx(title, rect.x, rect.y, halfWidth, 'left');
this.drawText(this.statusText(index), rect.x + halfWidth, rect.y, halfWidth, 'center');

Plugin commands:

• UpdateLocalizationTags - Checks json files from "data/" except ignored files specified in the plugin parameters and also all the parameters of all plugins. Found tags are saved in new files in the localization folder with the prefix "new".
• ClearLocalizationCache - Clears the localization cache.

Script calls:

Spoiler: Script calls

• DKTools.Localization.locale - Get current locale
• DKTools.Localization.locales - Get an array of locales
• DKTools.Localization.language - Get current language
• DKTools.Localization.languages - Get an array of languages
• DKTools.Localization.getText(text) - Get localized text
• DKTools.Localization.getPrevLocale() - Get previous locale
• DKTools.Localization.getNextLocale() - Get next locale
• DKTools.Localization.getPrevLanguage() - Get previous language
• DKTools.Localization.getNextLanguage() - Get next language
• DKTools.Localization.selectLocale(locale) - Set locale (async, returns Promise)
• DKTools.Localization.selectPrevLocale() - Select previous locale (async, returns Promise)
• DKTools.Localization.selectNextLocale() - Select next locale (async, returns Promise)
• DKTools.Localization.addChangeLocaleListener(function) - Add "change locale listener"
• DKTools.Localization.getPrimaryLocale() - Get primary locale
• DKTools.Localization.getPrimaryLanguage() - Get primary language

Help:

Spoiler: Help

###===========================================================================
## Special compatibility with other plugins
###===========================================================================
The plugin is compatible with most other plugins,
but plugins that do not work with localization can still be included.

## Attention! ##
If you think that any plugin is not compatible with localization, let me know.

###===========================================================================
## Used formats
###===========================================================================
The following formats can be used for translations:
1. JSON (details: https://en.wikipedia.org/wiki/JSON)
2. CSV (details: https://en.wikipedia.org/wiki/Comma-separated_values)
You can choose the format in the plugin settings.

### Attention! ###
The encoding in the translation files must be UTF-8 without BOM.
I recommend using Notepad++ for editing JSON files.
I recommend using Google Docs to edit CSV files.
Microsoft Office may not support UTF-8!

###===========================================================================
## Instructions
###===========================================================================

### 1 ### Installation ###
Add at least one language in the "Game languages" parameter.

## Incomplete list of recommended locales ##
Russian - ru
Ukrainian - uk
Belarusian - be
English - en
Chinese - zh
Japanese - ja
Korean - ko
French - fe
German - de
Spanish - es
Czech - cs
Italian - it

If you did not find a locale in this list, you can find it on the Internet, for example,
here: https://www.science.co.il/language/Locale-codes.php

### 2 ### Usage ###
1. When you first start the game,
the plugin will create a folders for translations and json files for each language (or csv file).
2. To localize text use the tags: {}.
3. To use a variable inside text use the tag: \VAR[ID],
where ID is the number of the variable. Use only for depth of translation (see below).

### Adding a new translation with an example of an event with a message (JSON) ###
1. Create a new event, add a message display.
2. In the message, write {text}. Save the event and project.
3. Open json files for each language.
4. The first character of the file must be {, and the last one - }.
These characters can not be deleted. Inside these brackets the translation of the game is written.
6. Add the following text to one of the files and save it: "text": "Text".
7. Start the game and the created event.

### Adding a new translation (CSV) ###
1. Open the csv file.
2. The first line is used for locales.
Locales must be registered starting from the second column!
3. The second and subsequent lines contain directly the translation of the text.
The first column must contain tags,
in the second and subsequent columns, the translation of tags, according to the locale.

###===========================================================================
## Using arrays (JSON only)
###===========================================================================
Arrays are loaded into the localization data by file name.

### Using arrays with the "quests.json" file as an example ###
1. The file has the following structure:
[null, { "name": "Quest 1" }, { "name": "Quest 2" }]
2. To display the text "Quest 1" in a message, you need to write a tag
{quests[1].name}
To access the array, you must first write the file name,
in which it is stored, then it must be indicated in square brackets
the element number and the field to be used.

###===========================================================================
## Localized resources
## Using different files (audio, images and videos) for each language
###===========================================================================
This function will help to use special files for different languages.
For example, if there is text on pictures, then you can make different pictures for each language,
and the plugin itself will select the desired picture.
This function works only with audio, video and images.

## Attention! ##
For this function to work on mobile devices and browsers,
you must set the Nwjs + Stamp file system mode in the DKTools plugin!

1. Create a new folder in your images folder
2. Use the required game locale as the folder name
3. Move the files to the created folder
Example:
It is necessary to use different images from the "img/pictures" folder for different languages.
Leave the image for the main (for example, English) language in the "img/pictures" folder.
Create an "ru" folder under "img/pictures" and move the image for Russian language there.
For example, for the English language, the main file from "img/pictures" will be used,
and for Russian from the folder "img/pictures/ru" we created.

## Attention! ##
Before publishing a game for browsers or mobile devices,
run the DKTools plugin command UpdateFileSystemStamp to update
file system stamp (more details in the DKTools plugin help)!

###===========================================================================
## Using an unlimited number of translation files
###===========================================================================
## Attention! ##
For this function to work on mobile devices and browsers,
you must set the Nwjs + Stamp file system mode in the DKTools plugin!
This instruction is intended for the folder that has a default name (locales)
If you renamed the folder in the plugin settings, then use the new folder name!

If you have a large amount of text in the game, and you are not comfortable using one json/csv file,
then you can split it into several json/csv files and put it in a separate folder.
In the case of CSV files, you must place all files in the localization folder,
subfolders are not supported!

Example for English locale (en) (JSON):
1. In the locales folder, create an "en" folder.
2. Transfer your old en.json file from the locales folder to the new folder.
3. Create several json files with any names.
4. In each file, write down the required tags and save the changes.
## Attention! ##
All tags in all files must have a unique name!
If the tag names match, the first one will be loaded (order is not guaranteed)!

### 3 ### Plugin parameters ###
1. Ignored files - Files that are ignored by the UpdateLocalizationTags and ExportAllText plugin commands.
2. Parse Depth - The number of text translation operations.
In the translated text you can specify another tag,
and it will be translated if the depth of translation is greater than 1.
Example:
"text": "Text {text2}",
"text2" "2"
With a translation depth of more than 1, the result is "Text 2".
3. Text Length - The length of the text at which it is saved in the cache.
This is necessary to reduce the computational resources for translation.
The cache is automatically cleared when between maps.

### 4 ### Message special symbols ###
1. \language - Display the name of the current language

### 5 ### Plugin commands ###
1. Extracts untranslated tags: UpdateLocalizationTags
The plugin command checks json files from "data/"
except ignored files specified in the plugin parameters
and also all the parameters of all plugins.
Found tags that are missing in the localization folder,
saved to a new files in the localization folder with the name "new_exported_tags".

2. Clear the localization cache: ClearLocalizationCache

3. Export all text: ExportAllText
The plugin command checks json files from "data/"
except ignored files specified in the plugin parameters
and also all the parameters of all plugins.
The found text are saved to the export.txt file in the localization folder.
Unlike the UpdateLocalizationTags command, it stores all text, not just tags.

### 6 ### Script calls ###
1. DKTools.Localization.locale - Get current locale
2. DKTools.Localization.locales - Get an array of locales
3. DKTools.Localization.language - Get current language
4. DKTools.Localization.languages - Get an array of languages
5. DKTools.Localization.getText(text) - Get localized text
6. DKTools.Localization.getPrevLocale() - Get previous locale
7. DKTools.Localization.getNextLocale() - Get next locale
8. DKTools.Localization.getPrevLanguage() - Get previous language
9. DKTools.Localization.getNextLanguage() - Get next language
10. DKTools.Localization.selectLocale(locale) - Set locale (async, returns Promise)
11. DKTools.Localization.selectPrevLocale() - Select previous locale (async, returns Promise)
12. DKTools.Localization.selectNextLocale() - Select next locale (async, returns Promise)
13. DKTools.Localization.addChangeLocaleListener(function) - Add "change locale listener" (sync/async function)
14. DKTools.Localization.getPrimaryLocale() - Get primary locale
15. DKTools.Localization.getPrimaryLanguage() - Get primary language

### 7 ### How to add the option to VisuMZ_1_OptionsCore.js ###
1. Place VisuMZ_1_OptionsCore plugin ABOVE in the plugin list
2. Enable "Show Options Command" parameter in the Localization plugin
3. Configure the new option in VisuMZ_1_OptionsCore.js with following parameters:
Symbol: locale
JS: Text:
return LocalizationParam.get('Options Command Name');
JS: Show/Hide:
return Imported['DKTools_Localization'] && LocalizationParam.get('Show Options Command');
JS: Draw Option:
const index = arguments[1];
const title = this.commandName(index);
const rect = this.itemLineRect(index);
const halfWidth = rect.width / 2;

this.resetFontSettings();
this.changePaintOpacity(true);
this.drawTextEx(title, rect.x, rect.y, halfWidth, 'left');
this.drawText(this.statusText(index), rect.x + halfWidth, rect.y, halfWidth, 'center');

### 8 ### Run on mobile devices and browsers ###
1. Make sure you have Nwjs + Stamp filesystem mode enabled in the DKTools plugin.
2. Before compiling the project, you must run the plugin command UpdateFileSystemStamp
from the DKTools plugin.
3. Compile the project for the required platform.
A description of the filesystem modes can be found in the DKTools plugin help.

### 9 ### Language switcher in messages ###
The function is designed to check messages in different languages.
To open the switcher window, use the configured key in the plugin parameters.
Default: T
The switcher does not work when entering numbers, selecting an item,
and the function may not work correctly if some plugins strongly change the message system.

I strongly recommend that you try the demo version before asking questions

Terms of use
You can:
-To use the plugin for your non-commercial projects
-Change code of the plugin

You cannot:
-Delete or change any information about the plugin
-Distribute the plugin and its modifications

Details on obtaining a commercial license on my website

Plugin page: https://dk-plugins.ru/mz/system/localization/

 

[Rex Tenebris]

What? A localization plugin that lets you choose the language even ingame without having to reload it?
And even has a demo project to know how it works?

No doubt, gonna use it in my project to bring it in english, japanese, spanish, italian, korean, chinese, albhed!!!
(okay... spanish and english at first launch because I don't know so much languages )
But!! It will help me a lot to translate my videogame in the future!
Nice launch!
...
"coming soon"
OUXCH!! Well, gonna check later if the demo is available

 

[DK]

What? A localization plugin that lets you choose the language even ingame without having to reload it?
And even has a demo project to know how it works?

No doubt, gonna use it in my project to bring it in english, japanese, spanish, italian, korean, chinese, albhed!!!
(okay... spanish and english at first launch because I don't know so much languages )
But!! It will help me a lot to translate my videogame in the future!
Nice launch!
...
"coming soon"
OUXCH!! Well, gonna check later if the demo is available

There is no demo yet, but it will be very soon. You can try the demo version of the plugin on MV. There is exactly the same functionality.

 

[Elliott404]

Does it require a core plugin like MV? Or is it independent?

 

[Elgigante94]

Nice job! No doubt it will usefull for many makers

 

[DK]

Does it require a core plugin like MV? Or is it independent?

Yes, also as the MV version. The plugin requires DKTools.

 

[Elliott404]

Alright. Thank you, sir.

 

[DK]

1. Updated first post
2. Added instruction for adding a language change option to the VisuMZ_1_OptionsCore plugin
3. Updated help

 

[Jhin]

Nice Job!

I'm using your plugin and it works like a charm. The option to split it in differents files is awesome!!

Thanks for your work!

 

[DK]

Plugin is publicly available

 

[r66r]

A really useful and very complete plugin to manage my multilingual games.

One question: Do you intend to allow some control characters from the original engine, such as "\.", "\|", "\!" or "\^"? They are useful to bring more dynamism to the message text.

In any case, thank you already for your work!

 

[DK]

A really useful and very complete plugin to manage my multilingual games.

One question: Do you intend to allow some control characters from the original engine, such as "\.", "\|", "\!" or "\^"? They are useful to bring more dynamism to the message text.

In any case, thank you already for your work!

Many thanks. To use special characters inside json files like "\!" they should write a double slash \\ like "\\!", this is a specificity of a json file, BUT for line breaks, you must use "\n" with a single slash.

 

[EthanFox]

This sounds great. I hope to give it a go in the future.

 

[r66r]

To use special characters inside json files like "\!" they should write a double slash \\ like "\\!"

Thank you for the answer. It works perfectly well. And I think I found where my issue were from.

Spoiler: Screenshots

Here is my JSON text:


If I call the message this way, it works as expected.


But what I was doing was that (I use a global event to display all texts).




And the result isn't as expected...

 

[SonaGate]

Is there a way to translate things from the Visustella Quest System? I'm trying but it doesn't work

EDIT: SOLVED.

 

[DK]

Version 1.1.3

What's new:

• Fixed bug in web version
• Added compatibility when migrating from very old versions of the plugin
• If there are json files in the locale folder, then the main.json file will not be created
• Help updated

 

[Koblas]

My bad, problem solved.

 

[DK]

Version 1.1.4

What's new:

• Added plugin command ExportAllText to export all text in a project (you can ignore localization tags)
• Fixed issue with preloading from DKTools plugin
• Help updated

 

[Tuomo L]

I can't get this to work, when I load up the game in the editor, it just creates empty main but nothing else even though I set {Level} and {Max_HP} as a test in the terms.

 

[DK]

I can't get this to work, when I load up the game in the editor, it just creates empty main but nothing else even though I set {Level} and {Max_HP} as a test in the terms.

You must also provide the translation for these tags in the json file (main.json)