Localization - Translate your project into several languages

じ☆ve冰风

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

Requirements and dependencies:

• Availability of working plugin DKToolsversion 1.3.5 or above
  

Features:

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


本贴来自国际rpgmaker官方论坛作者:DK处,因国际论坛即将永久关站,为了存档多年珍贵资料,署名转载到本论坛存档,由于官方帖子为英文原帖，需要中文翻译请点击论坛顶部切换语言为中文就可以将帖子翻译成中文浏览,方便大家随时查看,原文地址：https://forums.rpgmakerweb.com/threads/localization-translate-your-project-into-several-languages.126316/