This package has been deprecated

Author message:

Please use localized-resource-manager instead.

localizable-resources

ResourceManager.js

Provides the functionality to manage localized strings.

Table of Contents

• ResourceManager.js
  • Table of Contents
  • Install ResourceManager.js
  • Quickstart
    • Create Resource-Files
    • Use Resource-Files
  • Advanced Usage
    • Resources
    • ResourceSets
    • ResourceManager
    • Mustache-Flavored Strings
    • Working with Resource-Files
      • Resource-Files
        • Supported File-Types
          • JSON
          • JavaScript
          • YAML

Install ResourceManager.js

You can install ResourceManager.js using following command:

npm install --save localizable-resources

Quickstart

Create Resource-Files

Create a folder for holding resources and create resource-files with names in the following naming-convention:

{Resource-Name}[.{Culture-Name}].{File-Extension}

Examples: MyProject.json, MyProject.en.json, MyProject.en-US.json

Create some Key-Value pairs containing messages or other kinds of objects:

./Resources/MyProject.json

{
    "Message": "Hello",
    "Test": {
        "Message": "Hello World"
    }
}

Use Resource-Files

You can then use your resource-files by initializing a new ResourceManager:

import { CultureInfo } from "culture-info";
import { ResourceManager } from "localizable-resources";

let resource = new ResourceManager("./Resources/MyProject", CultureInfo.InvariantCulture);
console.log(resource.GetObject("Message"));
console.log(resource.GetObject("Test.Message")); // Test-Message from `MyProject.json`
console.log(resource.GetObject("Test.Message"), new CultureInfo("en")); // Test-Message from `MyProject.en.json`

Advanced Usage

Resources

If you don't care about localization and just want to store your objects and strings and stuff somewhere you may want to use one of the FileResource-classes.

That is

• JSONResource
• JavaScriptResource
• YAMLResource

You can use them by initializing as followed:

import * as Path from "path";
import { YAMLResource } from "localizable-resources";

let resource = new YAMLResource(Path.join("Resources", "MyProject.yml"));
console.log(resource.GetObject("Test"));

Resources are basically key-value-pairs containing messages, values etc. you want to use for your module.

ResourceSets

ResourceSets are a list of resources and their CultureInfo.
That said there can only be one resource per CultureInfo, which means that it's not possible to have two resource-files for de-CH, en etc.

import { ResourceSet } from "localizable-resources";

let resourceSet = new ResourceSet(
    [
        new CultureInfo("de"),
        new ObjectResource({})
    ],
    [
        new CultureInfo("de-CH"),
        new ObjectResource({})
    ]);

resourceSet.GetResource(new CultureInfo("de"));

ResourceManager

A resource-manager provides the functionality to automatically get the resource-object for the best-matching culture.
If you want to get a resource-object for de-CH and said resource-object couldn't be found the ResourceManager will automatically search the Resource for the German (de) culture. If this resource-object coudln't be found the ResourceManager will search the Resource for the invariant culture.

import CultureInfo from "culture-info";
import { ResourceManager } from "localizable-resources";

let resource = new ResourceManager(
    new ResourceSet(
        [
            CultureInfo.InvariantCulture,
            new ObjectResource({
                Test: "Invariant"
            })
        ],
        [
            new CultureInfo("de"),
            new ObjectResource({
                Test: "German"
            })
        ],
        [
            new CultureInfo("en-US"),
            new ObjectResource({
                Test: "English (United States)"
            });
        ]));

resource.Culture = new CultureInfo("de-CH");
console.log(resource.GetObject("Test", CultureInfo.InvariantCulture)); // "Invariant"
console.log(resource.GetObject("Test")) // "German"
resource.Culture = new CultureInfo("en-US");
console.log(resource.GetObject("Test")) // "English (United States)"

Mustache-Flavored Strings

The Resource and ResourceManager-classes provide the functionality to reuse parts of the Resource using mustache-flavored strings.

For instance:

import { ObjectResource } from "localizable-resources";

let resource = new ObjectResource({
    Hello: "Hallo",
    World: "Welt",
    HelloWorld: "{{Hello}}, du schöne {{World}}!"
});

console.log(resource.GetRawObject("HelloWorld")); // "{{Hello}}, du schöne {{World}}!
console.log(resource.GetObject("HelloWorld")); // "Hallo, du schöne Welt!"

This even works across multiple languages!

import CultureInfo from "culture-info";
import { ResourceManager } from "localizable-resources";

let resource = new ResourceManager(
    new ResourceSet(
        [
            new CultureInfo("de"),
            new ObjectResource({
                Street: "Straße",
                SomeLyrics: "Am Ende der {{Street}} steht ein Haus am See"
            })
        ],
        [
            new CultureInfo("de-CH"),
            new ObjectResource({
                Street: "Strasse"
            })
        ]));

resource.Culture = new CultureInfo("de");
console.log(resource.GetObject("SomeLyrics")); // "Am Ende der Straße steht ein Haus am See"
resource.Culture = new CultureInfo("de-CH");
console.log(resource.GetObject("SomeLyrics")); // "Am Ende der Strasse steht ein Haus am See"

Working with Resource-Files

Resource-Files

To make it all easy for you the ResourceManager provides the functionality to work with resource-files.

It's recommended to put resource-files into a separate directory to prevent the localizable-resources from getting confused.

The file-names of the resource-files must follow this naming-guideline:

{Resource-Name}[.{Culture-Name}].{File-Extension}

As you can see providing a culture-name is optional.
If you don't provide a culture-name the resource-file will be treated like a resoource-file for the invariant culture.

Please keep in mind that you can provide only one resource-file per culture.
This means that you can't create a MyProject.de.json alongside to a MyProject.de.yml.

The culture-name is a language-tag as described on w3.org.

Examples:

• MyProject.json
• MyProject.de.js
• MyProject.de-CH.yml

You can then use all of them using a code like this one:

import CultureInfo from "culture-info";
import { ResourceManager } from "localizable-resources";

// The baseFileName you have to provide is the
// path to the resource-files without the language-tag and file-extension.
let resource = new ResourceManager("./MyProject", new CultureInfo("de-CH"));
console.log(resource.GetObject("Key"));

There are only a few file-extensions supported yet.

Supported File-Types

JSON

Class: JSONResource
File-Extensions: .json
Example:

{
    "Key": "Value",
    "This": {
        "Is": {
            "An": "Example"
        }
    }
}

JavaScript

Class: JavaScriptResource
File-Extensions: .js
Example:

module.exports = {
    Key: "Value",
    This: {
        Is: {
            An: "Example"
        }
    }
}

YAML

Class: YAMLResource
File-Extensions: .yaml, .yml
Example:

Key: Value
This:
  Is:
    An: Example