classes language

Language

This class defines a global Language object to be used inside the API.

1. Static Properties/Functions

• Language.current: Language

  This is the global current language instance. You can change this value directly. Defaults to null, which means that the API has no default language anymore, and you will not be able to see the actual error messages unless you set a Language instance here by using some code like this: Language.current = new EnglishLanguage(API). This step is taken to minimize the file size.

• Language.resolveText(s: TemplateString, arr: string[]): string|null

  Converts a template string to a normal string using the given parameters in arr. Template string may include placeholders to represent the parameters. ("$1" for first parameter, "$2" for second parameter, and so on.) template string may also include the ? operator for simple logical branching. You may look at examples/languages/englishLanguage.js for some example usage.

  Parameters:

  • s: TemplateString: The template string to convert.
  • arr: string[]: Parameters to replace the placeholders in the template string.

  Return value: A finalized version of the template string that has all the placeholders replaced by the parameters, or null if something went wrong.

2. Language.prototype

Defines these functions that has to exist in every Language:

• Language.prototype.defineMetadata(metadata: object): void

  This function is called internally inside the constructor of all Language's by default. The function body is empty by default. This means that the metadata values are not stored in Language objects by default, because they are not useful in a non-GUI node.js environment. If we want to make use of the metadata, we might override this behavior by overriding this method. Remember that this should be done after initializing the API and before initializing any RoomConfigs.

  Parameters:

  • metadata: object: An object that holds some metadata values. This value might depend on what you want to do with this API. The examples in the GitHub repo are intended to be shown in a web application GUI that can be accessed by anyone. Therefore, they use the following structure for this object:
    • version: number: The current version number of this Language.
    • author: string: The author of this Language.
    • description: string: A detailed description of this Language.

  Return value: None.

  Default definition (in node.js):

  Language.prototype.defineMetadata = function(metadata){};

  Example (default) definition (in a complex website):

  Language.prototype.defineMetadata = function(metadata){
    this.metadata = metadata;
  };

3. constructor(abbr: string, metadata: object): void

Creates a new Language instance.

• abbr: string: Abbreviation of the new Language. Every Language should have a unique abbr, since the abbr is sent to plugins etc. via onLanguageChange signal for their own language customizations.
• metadata: object: Any information that we would want to show/update inside a GUI application about this Language. This is not used by the API by default, but we can reprogram the Language's prototype to make use of this value if we want. (For instructions, see section 2.)

4. Properties

• abbr: string: The abbreviation of this Language.
• api: object: The main data object that has all of the Language data of this API. By default, this object contains only an errors: object that must map all error codes to template strings.

Example Language definition:

// If you are using require.js library or in node.js, 
// API might also be defined via var API = require("node-haxball");
function TestLanguage(API){ 
	const {Language, Errors: {ErrorCodes}} = API;
	Object.setPrototypeOf(this, Language.prototype);
	Language.call(this, "TL", {
		name: "TestLanguage",
		version: "0.1",
		author: "abc",
		description: "This is a test language"
	});
	this.api = {
		errors: {
			[ErrorCodes.Empty]: "",
      // ... add all language text related to all of the error codes here.
    },
    // ... you may extend this class to include extra keys for your own GUI.
  };
}

Example usage:

This code sends a LanguageChange signal to all plugins, renderers, libraries and roomConfigs in all open rooms:

API.Language.current = new TestLanguage(API);

In order to catch it, we may use below code before writing the above code:

pluginOrRoomConfigEtc.onLanguageChange = (abbr)=>{
  // do something with abbr
};