@rollinsafary/phaser3-i18n-plugin

Description

This is i18n plugin for phaser 3 (https://github.com/photonstorm/phaser) It works only with phaser, because it uses jsons, that must be loaded into phaser game cache.

This plugin doesn't mutate original Phaser.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. This plugin adds factory and creator methods in Scene class for added types. It doesn't load json files again and again, it doesn't copy something or change something. It works automatically when I18nPlugin language is being chnaged. Every added game object type will emit I18nPlugin.LANGUAGE_CHANGED_EVENT event, when updates language.

How to use

I18nPlugin game objects will try to translate a value given to 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 "@rollinsafary/phaser3-ninepatch-plugin" plugin)

import { I18nCreator, I18nFactory, I18nPlugin } from '@rollinsafary/phaser3-i18n-plugin';
import { INinePatchCreator, INinePatchFactory } from '@rollinsafary/phaser3-ninepatch-plugin';


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)
  }
}

License MIT