Merge pull request #299 from cal-smith/i18n

feat(i18n): support observables and variables

Author: zvonimirfras

.gitignore

@@ -7,6 +7,7 @@ dist
 demo/bundle
 .idea
 .vscode
+.cache
 doc/
 documentation/
 dist/

src/i18n/en.json

@@ -95,7 +95,9 @@
 		"ITEMS_PER_PAGE": "Items per page:",
 		"OPEN_LIST_OF_OPTIONS": "Open list of options",
 		"BACKWARD": "Backward",
-		"FORWARD": "Forward"
+		"FORWARD": "Forward",
+		"TOTAL_ITEMS": "{{start}}-{{end}} of {{total}} items",
+		"TOTAL_PAGES": "{{current}} of {{last}} pages"
 	},
 	"TABLE": {
 		"GO_TO_PAGE": "Go to page",

src/i18n/i18n.module.ts

@@ -1,8 +1,10 @@
 import { NgModule, SkipSelf, Optional } from "@angular/core";
 
 import { I18n } from "./i18n.service";
+import { ReplacePipe } from "./replace.pipe";
 
-export { I18n } from "./i18n.service";
+export { I18n, replace } from "./i18n.service";
+export { ReplacePipe } from "./replace.pipe";
 
 // either provides a new instance of ModalPlaceholderService, or returns the parent
 export function I18N_SERVICE_PROVIDER_FACTORY(parentService: I18n) {
@@ -17,6 +19,8 @@ export const I18N_SERVICE_PROVIDER = {
 };
 
 @NgModule({
+	declarations: [ReplacePipe],
+	exports: [ReplacePipe],
 	providers: [
 		I18n,
 		I18N_SERVICE_PROVIDER

src/i18n/i18n.service.ts

@@ -1,16 +1,126 @@
 import { Injectable } from "@angular/core";
+import { BehaviorSubject } from "rxjs";
+import { map } from "rxjs/operators";
 
 const EN = require("./en.json");
 
+/**
+ * Takes the `Observable` returned from `i18n.get` and an object of variables to replace.
+ *
+ * The keys specify the variable name in the string.
+ *
+ * Example:
+ * ```typescript
+ * service.set({ "TEST": "{{foo}} {{bar}}" });
+ *
+ * service.replace(service.get("TEST"), { foo: "test", bar: "asdf" })
+ * ```
+ *
+ * Produces: `"test asdf"`
+ *
+ * @param subject the translation to replace variables on
+ * @param variables object of variables to replace
+ */
+export const replace = (subject, variables) => subject.pipe(
+	map<string, void>(str => {
+		const keys = Object.keys(variables);
+		for (const key of keys) {
+			const value = variables[key];
+			while (str.includes(`{{${key}}}`)) {
+				str = str.replace(`{{${key}}}`, value);
+			}
+		}
+		return str;
+	})
+);
+
+/**
+ * The I18n service is a minimal internal service used to supply our components with translated strings.
+ *
+ * All the components that support I18n also support directly passed strings.
+ * Usage of I18n is optional, and it is not recommended for application use (libraries like ngx-translate
+ * are a better choice)
+ *
+ */
 @Injectable()
 export class I18n {
 	protected translationStrings = EN;
 
+	protected translations = new Map();
+
+	/**
+	 * Set/update the translations from an object. Also notifies all participating components of the update.
+	 *
+	 * @param strings an object of strings, should follow the same format as src/i18n/en.json
+	 */
 	public set(strings) {
 		this.translationStrings = Object.assign({}, EN, strings);
+		const translations = Array.from(this.translations);
+		for (const [path, subject] of translations) {
+			subject.next(this.getValueFromPath(path));
+		}
+	}
+
+	/**
+	 * When a path is specified returns an observable that will resolve to the translation string value.
+	 *
+	 * Returns the full translations object if path is not specified.
+	 *
+	 * @param path optional, looks like `"NOTIFICATION.CLOSE_BUTTON"`
+	 */
+	public get(path?) {
+		if (!path) {
+			return this.translationStrings;
+		}
+		try {
+			// we run this here to validate the path exists before adding it to the translation map
+			const value = this.getValueFromPath(path);
+			if (this.translations.has(path)) {
+				return this.translations.get(path);
+			}
+			const translation = new BehaviorSubject(value);
+			this.translations.set(path, translation);
+			return translation;
+		} catch (err) {
+			console.error(err);
+		}
+	}
+
+	/**
+	 * Takes the `Observable` returned from `i18n.get` and an object of variables to replace.
+	 *
+	 * The keys specify the variable name in the string.
+	 *
+	 * Example:
+	 * ```
+	 * service.set({ "TEST": "{{foo}} {{bar}}" });
+	 *
+	 * service.replace(service.get("TEST"), { foo: "test", bar: "asdf" })
+	 * ```
+	 *
+	 * Produces: `"test asdf"`
+	 *
+	 * @param subject the translation to replace variables on
+	 * @param variables object of variables to replace
+	 */
+	public replace(subject, variables) {
+		return replace(subject, variables);
 	}
 
-	public get() {
-		return this.translationStrings;
+	/**
+	 * Trys to resolve a value from the provided path.
+	 *
+	 * @param path looks like `"NOTIFICATION.CLOSE_BUTTON"`
+	 */
+	protected getValueFromPath(path) {
+		let value = this.translationStrings;
+		for (const segment of path.split(".")) {
+			if (value[segment]) {
+				value = value[segment];
+			} else {
+				throw new Error(`no key ${segment} at ${path}`);
+			}
+		}
+		return value;
 	}
 }

src/i18n/i18n.spec.ts

@@ -0,0 +1,64 @@
+import { I18n } from "./i18n.service";
+
+const EN = require("./en.json");
+
+let service;
+
+describe("i18n service", () => {
+	beforeEach(() => {
+		service = new I18n();
+	});
+
+	it("should translate a string", done => {
+		service.get("BANNER.CLOSE_BUTTON").subscribe(value => {
+			expect(value).toBe(EN.BANNER.CLOSE_BUTTON);
+			done();
+		});
+	});
+
+	it("should update strings", done => {
+		service.set({ "BANNER": { "CLOSE_BUTTON": "test" }});
+
+		service.get("BANNER.CLOSE_BUTTON").subscribe(value => {
+			expect(value).toBe("test");
+			done();
+		});
+	});
+
+	it("should emit updated string", () => {
+		const subject = service.get("BANNER.CLOSE_BUTTON");
+
+		const spy = spyOn(subject, "next");
+
+		service.set({ "BANNER": { "CLOSE_BUTTON": "test" } });
+
+		expect(spy).toHaveBeenCalled();
+	});
+
+	it("should replace variables", done => {
+		service.set({ "TEST": "{{foo}} bar"});
+
+		service.replace(service.get("TEST"), {foo: "test"}).subscribe(value => {
+			expect(value).toBe("test bar");
+			done();
+		});
+	});
+
+	it("should replace multiple of the same variable", done => {
+		service.set({ "TEST": "{{foo}} {{foo}}" });
+
+		service.replace(service.get("TEST"), { foo: "test" }).subscribe(value => {
+			expect(value).toBe("test test");
+			done();
+		});
+	});
+
+	it("should replace multiple variables", done => {
+		service.set({ "TEST": "{{foo}} {{bar}}" });
+
+		service.replace(service.get("TEST"), { foo: "test", bar: "asdf" }).subscribe(value => {
+			expect(value).toBe("test asdf");
+			done();
+		});
+	});
+});

src/i18n/replace.pipe.ts

@@ -0,0 +1,11 @@
+import { Pipe, PipeTransform } from "@angular/core";
+import { replace } from "./i18n.service";
+
+@Pipe({
+	name: "i18nReplace"
+})
+export class ReplacePipe implements PipeTransform {
+	transform(value, variables) {
+		return replace(value, variables);
+	}
+}

src/notification/notification-content.interface.ts

@@ -4,7 +4,7 @@ export interface NotificationContent {
 	target?: string;
 	duration?: number;
 	smart?: boolean;
-	closeLabel?: string;
+	closeLabel?: any;
 	message: string;
 }
 

src/notification/notification.component.ts

@@ -11,6 +11,7 @@ import {
 import { NotificationContent } from "./notification-content.interface";
 import { I18n } from "./../i18n/i18n.module";
 import { NotificationDisplayService } from "./notification-display.service";
+import { of } from "rxjs";
 
 /**
  * Notification messages are displayed toward the top of the UI and do not interrupt user’s work.
@@ -33,7 +34,7 @@ import { NotificationDisplayService } from "./notification-display.service";
 		<button
 			(click)="onClose()"
 			class="bx--inline-notification__close-button"
-			[attr.aria-label]="notificationObj.closeLabel"
+			[attr.aria-label]="notificationObj.closeLabel | async"
 			type="button">
 			<svg
 				class="bx--inline-notification__close-icon"
@@ -59,6 +60,9 @@ export class Notification {
 		return this._notificationObj;
 	}
 	set notificationObj(obj: NotificationContent) {
+		if (obj.closeLabel) {
+			obj.closeLabel = of(obj.closeLabel);
+		}
 		this._notificationObj = Object.assign({}, this.defaultNotificationObj, obj);
 	}
 
@@ -87,7 +91,7 @@ export class Notification {
 		title: "",
 		message: "",
 		type: "info",
-		closeLabel: this.i18n.get().NOTIFICATION.CLOSE_BUTTON
+		closeLabel: this.i18n.get("NOTIFICATION.CLOSE_BUTTON")
 	};
 	protected _notificationObj: NotificationContent = Object.assign({}, this.defaultNotificationObj);
 

src/notification/notification.stories.ts

@@ -6,6 +6,7 @@ import { withKnobs, boolean, object } from "@storybook/addon-knobs/angular";
 import { Component } from "@angular/core";
 
 import { NotificationModule, NotificationService } from "./notification.module";
+import { I18n } from "../i18n/i18n.module";
 
 @Component({
 	selector: "app-notification-story",