diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 22197489c2..e2f906dafd 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -136,6 +136,7 @@ All definitions files include a header with the author and editors, so at some p * [http-string-parser](https://github.com/apiaryio/http-string-parser) (by [MIZUNE Pine](https://github.com/pine613)) * [Humane.js](http://wavded.github.com/humane-js/) (by [John Vrbanac](https://github.com/jmvrbanac)) * [i18next](http://i18next.com/) (by [Maarten Docter](https://github.com/mdocter)) +* [i18n-node](https://github.com/mashpie/i18n-node) (by [Maxime LUCE](https://github.com/SomaticIT)) * [iCheck](http://damirfoy.com/iCheck/) (by [Dániel Tar](https://github.com/qcz)) * [Impress.js](https://github.com/bartaz/impress.js) (by [Boris Yankov](https://github.com/borisyankov)) * [Imagemagick](http://github.com/rsms/node-imagemagick) (by [Carlos Ballesteros Velasco](https://github.com/soywiz)) diff --git a/i18n-node/i18n-node-tests.ts b/i18n-node/i18n-node-tests.ts new file mode 100644 index 0000000000..f4403e5c10 --- /dev/null +++ b/i18n-node/i18n-node-tests.ts @@ -0,0 +1,140 @@ +/** + * Test suite created by Maxime LUCE + * + * Created by using code samples from https://github.com/mashpie/i18n-node. + */ + +/// +/// +/// + +import express = require("express"); +import i18n = require("i18n"); + +var app = express(); +var req: express.Request; + +/** + * Configuration + * https://github.com/mashpie/i18n-node#configure + */ +i18n.configure({ + locales: ['en', 'de'], + directory: __dirname + '/locales' +}); + +i18n.configure({ + // setup some locales - other locales default to en silently + locales: ['en', 'de'], + + // you may alter a site wide default locale + defaultLocale: 'de', + + // sets a custom cookie name to parse locale settings from - defaults to NULL + cookie: 'yourcookiename', + + // where to store json files - defaults to './locales' relative to modules directory + directory: './mylocales', + + // whether to write new locale information to disk - defaults to true + updateFiles: false, + + // what to use as the indentation unit - defaults to "\t" + indent: "\t", + + // setting extension of json files - defaults to '.json' (you might want to set this to '.js' according to webtranslateit) + extension: '.js', + + // setting prefix of json files name - default to none '' (in case you use different locale files naming scheme (webapp-en.json), rather then just en.json) + prefix: 'webapp-', + + // enable object notation + objectNotation: false +}); + +/** + * Usage in global scope + * https://github.com/mashpie/i18n-node#example-usage-in-global-scope + */ +var greeting = i18n.__('Hello'); + +/** + * Usage in Express + * https://github.com/mashpie/i18n-node#example-usage-in-expressjs + */ +// Configuration +app.configure(function () { + // default: using 'accept-language' header to guess language settings + app.use(i18n.init); +}); + +app.get('/de', function (_req, res) { + var greeting = res.__('Hello'); +}); + +/** + * __() + * https://github.com/mashpie/i18n-node#__ + */ +// global (this.locale == 'de') +i18n.__('Hello'); // Hallo +i18n.__('Hello %s', 'Marcus'); // Hallo Marcus +i18n.__('Hello {{name}}', { name: 'Marcus' }); // Hallo Marcus + +// scoped via req object (req.locale == 'de') +req.__('Hello'); // Hallo +req.__('Hello %s', 'Marcus'); // Hallo Marcus +req.__('Hello {{name}}', { name: 'Marcus' }); // Hallo Marcus + +// passing specific locale +i18n.__({ phrase: 'Hello', locale: 'fr' }); // Salut +i18n.__({ phrase: 'Hello %s', locale: 'fr' }, 'Marcus'); // Salut Marcus +i18n.__({ phrase: 'Hello {{name}}', locale: 'fr' }, { name: 'Marcus' }); // Salut Marcus + +/** + * __n() + * https://github.com/mashpie/i18n-node#__n + */ +// global (this.locale == 'de') +i18n.__n("%s cat", "%s cats", 1); // 1 Katze +i18n.__n("%s cat", "%s cats", 3); // 3 Katzen + +// scoped via req object (req.locale == 'de') +req.__n("%s cat", "%s cats", 1); // 1 Katze +req.__n("%s cat", "%s cats", 3); // 3 Katzen + +// passing specific locale +i18n.__n({ singular: "%s cat", plural: "%s cats", locale: "fr" }, 1); // 1 chat +i18n.__n({ singular: "%s cat", plural: "%s cats", locale: "fr" }, 3); // 3 chat +i18n.__n({ singular: "%s cat", plural: "%s cats", locale: "fr", count: 1 }); // 1 chat +i18n.__n({ singular: "%s cat", plural: "%s cats", locale: "fr", count: 3 }); // 3 chat + +/** + * setLocale() + * https://github.com/mashpie/i18n-node#setlocale + */ +i18n.setLocale('de'); +i18n.setLocale(req, 'de'); +req.setLocale('de'); + +/** + * getLocale() + * https://github.com/mashpie/i18n-node#getlocale + */ +i18n.getLocale(); // --> de +i18n.getLocale(req); // --> de +req.getLocale(); // --> de + +/** + * getCatalog() + * https://github.com/mashpie/i18n-node#getcatalog + */ +i18n.getCatalog(); // returns all locales +i18n.getCatalog('de'); // returns just 'de' + +i18n.getCatalog(req); // returns all locales +i18n.getCatalog(req, 'de'); // returns just 'de' + +req.getCatalog(); // returns all locales +req.getCatalog('de'); // returns just 'de' + diff --git a/i18n-node/i18n-node.d.ts b/i18n-node/i18n-node.d.ts new file mode 100644 index 0000000000..348c2f2689 --- /dev/null +++ b/i18n-node/i18n-node.d.ts @@ -0,0 +1,339 @@ +// Type definitions for i18n-node 0.5.0 +// Project: https://github.com/mashpie/i18n-node +// Definitions by: Maxime LUCE +// Definitions: https://github.com/borisyankov/DefinitelyTyped + +/// +declare module i18n { + export interface ConfigurationOptions { + /** Setup some locales - other locales default to en silently */ + locales?: string[]; + /** Alter a site wide default locale */ + defaultLocale?: string; + + /** + * Sets a custom cookie name to parse locale settings from + * @default null + */ + cookie?: string; + /** + * Where to store json files, relative to modules directory + * @default "./locales" + */ + directory?: string; + + /** + * whether to write new locale information to disk + * @default true + */ + updateFiles?: boolean; + + /** + * What to use as the indentation unit + * @default "\t" + */ + indent?: string; + + /** + * Setting extension of json files (you might want to set this to '.js' according to webtranslateit) + * @default ".json" + */ + extension?: string; + + /** + * Enable object notation + * @default false + */ + objectNotation?: boolean; + } + export interface TranslateOptions { + phrase: string; + locale?: string; + } + export interface PluralOptions { + singular: string; + plural: string; + count?: number; + locale?: string; + } + export interface Replacements { + [key: string]: string; + } + + export interface LocaleCatalog { + [key: string]: string; + } + export interface GlobalCatalog { + [key: string]: LocaleCatalog; + } + + /** + * Configure current i18n instance + * @param {ConfigurationOptions} options - configuration options for i18n + */ + function configure(options: ConfigurationOptions): void; + + /** + * Initialize i18n middleware for express + * @param {Express.Request} request - Current express request + * @param {Express.Response} response - Current express response + * @param {Function} next - Callback to continue process + */ + function init(request: Express.Request, response: Express.Response, next?: Function): void; + + //#region __() + + /** + * Translate the given phrase using locale configuration + * @param {string} phrase - The phrase to translate + * @returns {string} The translated phrase + */ + function __(phrase: string, ...replace: string[]): string; + /** + * Translate the given phrase using locale configuration + * @param {string} phrase - The phrase to translate + * @param {Object} replacements - An object containing replacements + * @returns {string} The translated phrase + */ + function __(phrase: string, replacements: Replacements): string; + /** + * Translate the given phrase using locale configuration + * @param {TranslateOptions} options - Options for translation + * @returns {string} The translated phrase + */ + function __(options: TranslateOptions): string; + /** + * Translate the given phrase using locale configuration + * @param {TranslateOptions} options - Options for translation + * @returns {string} The translated phrase + */ + function __(options: TranslateOptions, ...replace: string[]): string; + /** + * Translate the given phrase using locale configuration + * @param {TranslateOptions} options - Options for translation + * @param {Object} replacements - An object containing replacements + * @returns {string} The translated phrase + */ + function __(options: TranslateOptions, replacements: Replacements): string; + + //#endregion + + //#region __n() + + /** + * Translate with plural condition the given phrase and count using locale configuration + * @param {PluralOptions} options - Options for plural translate + * @returns {string} The translated phrase + */ + function __n(options: PluralOptions): string; + + /** + * Translate with plural condition the given phrase and count using locale configuration + * @param {PluralOptions} options - Options for plural translate + * @param {number} count - The number which allow to select from plural to singular + * @returns {string} The translated phrase + */ + function __n(options: PluralOptions, count: number): string; + /** + * Translate with plural condition the given phrase and count using locale configuration + * @param {string} singular - The singular pharse to translate if count is <= 1 + * @param {string} plural - The plural pharse to translate if count is > 1 + * @param {number} count - The number which allow to select from plural to singular + * @returns {string} The translated phrase + */ + function __n(singular: string, plural: string, count: number): string; + /** + * Translate with plural condition the given phrase and count using locale configuration + * @param {string} singular - The singular pharse to translate if count is <= 1 + * @param {string} plural - The plural pharse to translate if count is > 1 + * @param {number} count - The number which allow to select from plural to singular + * @returns {string} The translated phrase + */ + function __n(singular: string, plural: string, count: string): string; + + //#endregion + + //#region Locale + + /** + * Change the current active locale + * @param {string} locale - The locale to set as default + */ + function setLocale(locale: string): void; + /** + * Change the current active locale for specified request + * @param {Express.Request} request - The request to change locale on + * @param {string} locale - The locale to set as default + */ + function setLocale(request: Express.Request, locale: string): void; + + /** + * Get the current active locale + * @returns {string} The current locale in request + */ + function getLocale(): string; + /** + * Get the current active locale for specified request + * @param {Express.Request} request - The request to get locale for + * @returns {string} The current locale in request + */ + function getLocale(request: Express.Request): string; + + //#endregion + + //#region Catalog + + /** + * Get the current global catalog + * @returns {GlobalCatalog} The current global catalog + */ + function getCatalog(): GlobalCatalog; + /** + * Get the catalog for the given locale + * @param {string} locale - The locale to get catalog for + * @returns {LocaleCatalog} The specified locale catalog + */ + function getCatalog(locale: string): LocaleCatalog; + /** + * Get the current active locale catalog for specified request + * @param {Express.Request} request - The request to get locale catalog for + * @returns {LocaleCatalog} The current locale catalog for the specified request + */ + function getCatalog(request: Express.Request): LocaleCatalog; + /** + * Get the current locale catalog for specified request and specified locale + * @param {Express.Request} request - The request to get locale catalog for + * @param {string} locale - The locale to get catalog for + * @returns {LocaleCatalog} The specified locale catalog + */ + function getCatalog(request: Express.Request, locale: string): LocaleCatalog; + + //#endregion + + /** + * Override the current request locale by using the query param (?locale=en) + * @param {Express.Request} [request] - The request to override locale for + */ + function overrideLocaleFromQuery(request?: Express.Request): void; + + /** + * Get current i18n-node version + * @member {string} + */ + var version: string; +} + +interface i18nAPI { + locale: string; + + //#region __() + + /** + * Translate the given phrase using locale configuration + * @param {string} phrase - The phrase to translate + * @returns {string} The translated phrase + */ + __(phrase: string, ...replace: string[]): string; + /** + * Translate the given phrase using locale configuration + * @param {string} phrase - The phrase to translate + * @param {Object} replacements - An object containing replacements + * @returns {string} The translated phrase + */ + __(phrase: string, replacements: i18n.Replacements): string; + /** + * Translate the given phrase using locale configuration + * @param {TranslateOptions} options - Options for translation + * @returns {string} The translated phrase + */ + __(options: i18n.TranslateOptions): string; + /** + * Translate the given phrase using locale configuration + * @param {TranslateOptions} options - Options for translation + * @returns {string} The translated phrase + */ + __(options: i18n.TranslateOptions, ...replace: string[]): string; + /** + * Translate the given phrase using locale configuration + * @param {TranslateOptions} options - Options for translation + * @param {Object} replacements - An object containing replacements + * @returns {string} The translated phrase + */ + __(options: i18n.TranslateOptions, replacements: i18n.Replacements): string; + + //#endregion + + //#region __n() + + /** + * Translate with plural condition the given phrase and count using locale configuration + * @param {PluralOptions} options - Options for plural translate + * @returns {string} The translated phrase + */ + __n(options: i18n.PluralOptions): string; + + /** + * Translate with plural condition the given phrase and count using locale configuration + * @param {PluralOptions} options - Options for plural translate + * @param {number} count - The number which allow to select from plural to singular + * @returns {string} The translated phrase + */ + __n(options: i18n.PluralOptions, count: number): string; + /** + * Translate with plural condition the given phrase and count using locale configuration + * @param {string} singular - The singular pharse to translate if count is <= 1 + * @param {string} plural - The plural pharse to translate if count is > 1 + * @param {number} count - The number which allow to select from plural to singular + * @returns {string} The translated phrase + */ + __n(singular: string, plural: string, count: number): string; + /** + * Translate with plural condition the given phrase and count using locale configuration + * @param {string} singular - The singular pharse to translate if count is <= 1 + * @param {string} plural - The plural pharse to translate if count is > 1 + * @param {number} count - The number which allow to select from plural to singular + * @returns {string} The translated phrase + */ + __n(singular: string, plural: string, count: string): string; + + //#endregion + + /** + * Get the current active locale + * @returns {string} The current locale in request + */ + getLocale(): string; + /** + * Change the current active locale + * @param {string} locale - The locale to set as default + */ + setLocale(locale: string): void; + + /** + * Get the current global catalog + * @returns {GlobalCatalog} The current global catalog + */ + getCatalog(): i18n.GlobalCatalog; + /** + * Get the catalog for the given locale + * @param {string} locale - The locale to get catalog for + * @returns {LocaleCatalog} The specified locale catalog + */ + getCatalog(locale: string): i18n.LocaleCatalog; +} + +declare module "i18n" { + export = i18n; +} + +declare module Express { + export interface Request extends i18nAPI { + languages: string[]; + regions: string[]; + language: string; + region: string; + } + export interface Response extends i18nAPI { + locals: i18nAPI + } +}