Simple I18n plugin for Phaser 3
npm install @candywings/phaser3-i18n-pluginPhaser.GameObjects.Text, Phaser.GameObjects.BitmapText and Phaser.GameObjects.DynamicBitmapText types. It bring it's own text types for each of these types ExtendedText, ExtendedBitmapText, ExtendedDynamicBitmapText.
Scene class for added types.
I18nPlugin.LANGUAGE_CHANGED_EVENT event, when updates language.
text property, if there's no translation given value will be shown.
this.make.extBitmapText(
{
...other params,
text: 'word-hello'.
},
true // addToScene?: boolean
)
// returns object of type ExtendedBitmapText that extends Phaser.GameObjects.BitmapText
// English: hello
// Russian: привет
`
---
You can use dynamic translations, for example you can have a json like this
`
// en.json
{
"word-hello": "hello",
"phrase-my-name": "my name is {{playerName}}"
}
`
`
// ru.json
{
"word-hello": "привет",
"phrase-my-name": "меня зовут {{playerName}}"
}
`
and you can concate the translations
`
this.make.extText(
{
...other params,
text: this.scene.i18n.translate('word-hello') + ', ', + this.scene.i18n.translate('phrase-my-name', {
playerName: "Rollin Safary",
}).
},
true // addToScene?: boolean
)
// returns object of type ExtendedText that extends Phaser.GameObjects.Text
// English: hello, my name is Rollin Safary
// Russian: привет, меня зовут Rollin Safary
`
npm install @candywings/phaser3-i18n-plugin
##Setup
Example codes are provided on TypeScript.
#### Game
`
import { I18nGame, I18nPlugin } from '@candywings/phaser3-i18n-plugin';
export default class Game extends I18nGame {
constructor(config: Phaser.Core.Config) {
super(generateGameConfiguration());
this.setupI18n();
}
public setupI18n(): void {
this.i18n = new I18nPlugin(this, {
languages: [
{ key: 'en', keyJSON: 'translation-en' },
{ key: 'ru', keyJSON: 'translation-ru' },
],
language: 'en',
valueInjectorOpener: '{{',
valueInjectorCloser: '}}',
fontMappings: [] // More info in CHANGELOG v1.0.1
bitmapFontMappings: [] // More info in CHANGELOG v1.0.1
});
}
}
`
#### BaseScene
(if you aren't using other plugin that adds something to scene's factory and creator)
`
import { I18nScene } from '@candywings/phaser3-i18n-plugin';
export default class BaseScene extends I18nScene {
public init():void {
this.i18n = this.game.i18n;
}
}
`
(if you are using other plugin that adds something to scene's factory and creator, for example "@koreez/phaser3-ninepatch@^1.2.5 plugin)
`
import { I18nCreator, I18nFactory, I18nPlugin } from '@candywings/phaser3-i18n-plugin';
import { INinePatchCreator, INinePatchFactory } from '@koreez/phaser3-ninepatch';
export default class BootScene extends Phaser.Scene {
public add: INinePatchFactory & I18nFactory;
public make: INinePatchCreator & I18nCreator;
public i18n: I18nPlugin
public init():void {
this.i18n = this.game.i18n;
}
}
`
#### BootScene
`
import { I18nCreator, I18nFactory, I18nScene } from '@candywings/phaser3-i18n-plugin';
export default class BootScene extends BaseScene {
public preload():void {
// load your translation jsons here via phaser loader
}
public create():void {
this.i18n.init();
}
}
`
All scenes extended from I18nScene have i18n proeprty, but that's not a copy of plugin instance, it's just a reference to Game's i18n property.
#### Change language
To change game language you need just call to call
from scene: this.i18n.changeLanguage(languageToSwitch) or this.game.i18n.changeLanguage(languageToSwitch),
from gameObject: this.scene.i18n.changeLanguage(languageToSwitch). Don't forget that your gameObject's scene must be extended from I18nScene, to have property i18n in it.
Possible mistakes in usage
1. If you have original text object, it won't listen language change event and won't translate it's text.
2. Plugin config fontMappings applies only on ExtendedText objects and not ExtendedBitmapText or ExtendedDynamicBitmapText objects. Same for bitmapFontMappings.
Best practice
1. If you want to use concated translations, the best way is to use original text object and listen for I18nPlugin.LANGUAGE_CHANGED_EVENT on this.i18n (if you're in scene) or this.scene.i18n.
2. For typescript users: if you have custom gameObject, and logic in it, to say that it's scene is I18nScene extended just add in you class
`
protected scene: I18nScene
`
example
Method 1:
`
export class MyCustomGameObject extends Phaser.GameObjects.GameObject {
protected scene: I18nScene
}
`
Method 2:
`
export class MyCustomGameObject extends Phaser.GameObjects.GameObject {
constructor(protected scene: I18nScene, ...args){
super(scene, ...args)
}
}
``