@enonic-types/lib-i18n 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# Enonic XP lib-i18n TS types
+
+> TypeScript definitions for `lib-i18n` library of Enonic XP
+
+## Install
+
+```bash
+npm i --save-dev @enonic/lib-i18n
+```
+
+## Use
+
+Add the corresponding types to your `tsconfig.json` file that is used for application's server-side TypeScript code.
+
+`tsconfig.json`
+```json
+{
+  "compilerOptions": {
+    "types": [
+      "@enonic-types/lib-i18n"
+    ]
+  }
+}
+```
+
+### Require and custom imports
+
+To make `require` work out of box, you must install and add the `@enonic-types/global` types. Aside from providing definitions for XP global objects, e.g. `log`, `app`, `__`, etc, requiring library by the default path will return typed object.
+
+`tsconfig.json`
+```diff
+{
+  "compilerOptions": {
+    "types": [
++     "@enonic-types/global"
+      "@enonic-types/lib-i18n"
+    ]
+  }
+}
+```
+
+`example.ts`
+```ts
+const {localize, getPhrases, getSupportedLocales} = require('/lib/xp/i18n');
+```
+
+More detailed explanation on how it works and how to type custom import function can be found [here](https://github.com/enonic/xp/tree/master/modules/lib/typescript/README.md).
+
+### ES6-style import
+
+If you are planning to use `import` in your code and transpile it with the default `tsc` TypeScript compiler, you'll need to add proper types mapping to your configuration.
+
+`tsconfig.json`
+```diff
+{
+  "compilerOptions": {
+    "types": [
+      "@enonic-types/lib-i18n"
+    ]
++   "baseUrl": "./",
++   "paths": {
++     "/lib/xp/i18n": ["node_modules/@enonic-types/lib-i18n"],
++   }
+  }
+}
+```
+
+`example.ts`
+```ts
+import {localize, getPhrases, getSupportedLocales} from '/lib/xp/i18n';
+```
+
+Setting `baseUrl` and `paths` will allow the `tsc` to keep the valid paths in the resulting JavaScript files.

package/i18n.d.ts

@@ -0,0 +1,55 @@
+declare global {
+    interface XpLibraries {
+        '/lib/xp/i18n': typeof import('./i18n');
+    }
+}
+export interface LocalizeParams {
+    key: string;
+    locale?: string | string[];
+    values?: string[];
+    bundles?: string[];
+    application?: string;
+}
+/**
+ * Internationalization functions.
+ *
+ * @example
+ * var i18nLib = require('/lib/xp/i18n');
+ *
+ * @module i18n
+ */
+/**
+ * This function localizes a phrase.
+ *
+ * @example-ref examples/i18n/localize.js
+ *
+ * @param {object} params JSON with the parameters.
+ * @param {string} params.key The property key.
+ * @param {string|string[]} [params.locale] A string-representation of a locale, or an array of locales in preferred order. If the locale is not set, the site language is used.
+ * @param {string[]} [params.values] Optional placeholder values.
+ * @param {string[]} [params.bundles] Optional list of bundle names.
+ * @param {string} [params.application] Application key where to find resource bundles. Defaults to current application.
+ *
+ * @returns {string} The localized string.
+ */
+export declare function localize(params: LocalizeParams): string;
+/**
+ * This function returns all phrases for the given locale and bundles.
+ *
+ * @param {string|string[]} locale A string-representation of a locale, or an array of locales in preferred order.
+ * @param {string[]} bundles List of bundle names.  Bundle names are specified as paths, relative to the `src/main/resources` folder.
+ *
+ * @returns {object} An object of all phrases.
+ *
+ * @example
+ * i18nLib.getPhrases('en', ['i18n/phrases'])
+ */
+export declare function getPhrases(locale: string | string[], bundles: string[]): Record<string, string>;
+/**
+ * This function returns the list of supported locale codes for the specified bundles.
+ *
+ * @param {string[]} bundles List of bundle names.
+ *
+ * @returns {string[]} A list of supported locale codes for the specified bundles.
+ */
+export declare function getSupportedLocales(bundles: string[]): string[];

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "@enonic-types/lib-i18n",
+    "version": "0.1.0",
+    "description": "Type definitions for lib-i18n.",
+    "types": "i18n.d.ts",
+    "files": [
+        "i18n.d.ts"
+    ],
+    "scripts": {
+        "pre": "npm run --prefix ../ pre",
+        "packlist": "npx npm-packlist"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/enonic/xp.git#master"
+    },
+    "keywords": [
+        "enonic",
+        "enonic-xp",
+        "lib-i18n",
+        "i18n",
+        "types",
+        "typescript"
+    ],
+    "contributors": [
+        "Mikita Taukachou <edloidas@gmail.com> (https://edloidas.github.io/)"
+    ],
+    "license": "Apache-2.0",
+    "bugs": {
+        "url": "https://github.com/enonic/xp/issues"
+    },
+    "homepage": "https://github.com/enonic/xp/tree/master#readme",
+    "publishConfig": {
+        "access": "public"
+    }
+}