carbon-components-angular
Version:
Next generation components
1,220 lines (1,041 loc) • 58.4 kB
HTML
<!doctype html>
<html class="no-js" lang="">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<title>carbon-components-angular documentation</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/x-icon" href="../images/favicon.ico">
<link rel="stylesheet" href="../styles/style.css">
<link rel="stylesheet" href="../styles/dark.css">
<style>
footer.carbon {
position: absolute;
bottom: 0;
width: 100%;
z-index: 9999;
}
#root > div {
/*
* Subtracting the height of the footer to prevent
* overlaying the footer ontop of content
*/
height: calc(100vh - 48px);
}
</style>
</head>
<body>
<script>
// Blocking script to avoid flickering dark mode
// Dark mode toggle button
var useDark = window.matchMedia('(prefers-color-scheme: dark)');
var darkModeState = useDark.matches;
var $darkModeToggleSwitchers = document.querySelectorAll('.dark-mode-switch input');
var $darkModeToggles = document.querySelectorAll('.dark-mode-switch');
var darkModeStateLocal = localStorage.getItem('compodoc_darkmode-state');
function checkToggle(check) {
for (var i = 0; i < $darkModeToggleSwitchers.length; i++) {
$darkModeToggleSwitchers[i].checked = check;
}
}
function toggleDarkMode(state) {
if (window.localStorage) {
localStorage.setItem('compodoc_darkmode-state', state);
}
checkToggle(state);
const hasClass = document.body.classList.contains('dark');
if (state) {
for (var i = 0; i < $darkModeToggles.length; i++) {
$darkModeToggles[i].classList.add('dark');
}
if (!hasClass) {
document.body.classList.add('dark');
}
} else {
for (var i = 0; i < $darkModeToggles.length; i++) {
$darkModeToggles[i].classList.remove('dark');
}
if (hasClass) {
document.body.classList.remove('dark');
}
}
}
useDark.addEventListener('change', function (evt) {
toggleDarkMode(evt.matches);
});
if (darkModeStateLocal) {
darkModeState = darkModeStateLocal === 'true';
}
toggleDarkMode(darkModeState);
</script>
<div class="navbar navbar-default navbar-fixed-top d-md-none p-0">
<div class="d-flex">
<a href="../" class="navbar-brand">carbon-components-angular documentation</a>
<button type="button" class="btn btn-default btn-menu ion-ios-menu" id="btn-menu"></button>
</div>
</div>
<div class="xs-menu menu" id="mobile-menu">
<div id="book-search-input" role="search"><input type="text" placeholder="Type to search"></div> <compodoc-menu></compodoc-menu>
</div>
<div class="container-fluid main">
<div class="row main">
<div class="d-none d-md-block menu">
<compodoc-menu mode="normal"></compodoc-menu>
</div>
<!-- START CONTENT -->
<div class="content injectable">
<div class="content-data">
<ol class="breadcrumb">
<li class="breadcrumb-item">Injectables</li>
<li class="breadcrumb-item" >I18n</li>
</ol>
<ul class="nav nav-tabs" role="tablist">
<li class="nav-item">
<a href="#info"
class="nav-link"
class="nav-link active"
role="tab" id="info-tab" data-bs-toggle="tab" data-link="info">Info</a>
</li>
<li class="nav-item">
<a href="#source"
class="nav-link"
role="tab" id="source-tab" data-bs-toggle="tab" data-link="source">Source</a>
</li>
</ul>
<div class="tab-content">
<div class="tab-pane fade active in" id="info">
<p class="comment">
<h3>File</h3>
</p>
<p class="comment">
<code>src/i18n/i18n.service.ts</code>
</p>
<p class="comment">
<h3>Description</h3>
</p>
<p class="comment">
<p>The I18n service is a minimal internal singleton service used to supply our components with translated strings.</p>
<p>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)</p>
</p>
<section data-compodoc="block-index">
<h3 id="index">Index</h3>
<table class="table table-sm table-bordered index-table">
<tbody>
<tr>
<td class="col-md-4">
<h6><b>Properties</b></h6>
</td>
</tr>
<tr>
<td class="col-md-4">
<ul class="index-list">
<li>
<span class="modifier">Protected</span>
<a href="#locale" >locale</a>
</li>
<li>
<span class="modifier">Protected</span>
<a href="#translations" >translations</a>
</li>
<li>
<span class="modifier">Protected</span>
<a href="#translationStrings" >translationStrings</a>
</li>
</ul>
</td>
</tr>
<tr>
<td class="col-md-4">
<h6><b>Methods</b></h6>
</td>
</tr>
<tr>
<td class="col-md-4">
<ul class="index-list">
<li>
<span class="modifier">Public</span>
<a href="#get" >get</a>
</li>
<li>
<span class="modifier">Public</span>
<a href="#getLocale" >getLocale</a>
</li>
<li>
<span class="modifier">Public</span>
<a href="#getLocaleObservable" >getLocaleObservable</a>
</li>
<li>
<span class="modifier">Public</span>
<a href="#getMultiple" >getMultiple</a>
</li>
<li>
<span class="modifier">Public</span>
<a href="#getOverridable" >getOverridable</a>
</li>
<li>
<span class="modifier">Protected</span>
<a href="#getSubject" >getSubject</a>
</li>
<li>
<span class="modifier">Public</span>
<a href="#getValueFromPath" >getValueFromPath</a>
</li>
<li>
<span class="modifier">Public</span>
<a href="#replace" >replace</a>
</li>
<li>
<span class="modifier">Public</span>
<a href="#set" >set</a>
</li>
<li>
<span class="modifier">Public</span>
<a href="#setLocale" >setLocale</a>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
</section>
<section data-compodoc="block-methods">
<h3 id="methods">
Methods
</h3>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="get"></a>
<span class="name">
<span class="modifier">Public</span>
<span ><b>get</b></span>
<a href="#get"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>get(path?: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</a>)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="210"
class="link-to-prism">src/i18n/i18n.service.ts:210</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>When a path is specified returns an observable that will resolve to the translation string value.</p>
<p>Returns the full translations object if path is not specified.</p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>path</td>
<td>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank" >string</a></code>
</td>
<td>
Yes
</td>
<td>
<p>optional, looks like <code>"NOTIFICATION.CLOSE_BUTTON"</code></p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >any</a></code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="getLocale"></a>
<span class="name">
<span class="modifier">Public</span>
<span ><b>getLocale</b></span>
<a href="#getLocale"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>getLocale()</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="178"
class="link-to-prism">src/i18n/i18n.service.ts:178</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Returns the current locale</p>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >any</a></code>
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="getLocaleObservable"></a>
<span class="name">
<span class="modifier">Public</span>
<span ><b>getLocaleObservable</b></span>
<a href="#getLocaleObservable"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>getLocaleObservable()</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="185"
class="link-to-prism">src/i18n/i18n.service.ts:185</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Returns an observable that resolves to the current locale, and will update when changed</p>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >any</a></code>
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="getMultiple"></a>
<span class="name">
<span class="modifier">Public</span>
<span ><b>getMultiple</b></span>
<a href="#getMultiple"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>getMultiple(partialPath: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</a>)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="222"
class="link-to-prism">src/i18n/i18n.service.ts:222</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Returns all descendents of some path fragment as an object.</p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>partialPath</td>
<td>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank" >string</a></code>
</td>
<td>
No
</td>
<td>
<p>a path fragment, for example <code>"NOTIFICATION"</code></p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="io-description">
<b>Returns : </b> <code>literal type</code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="getOverridable"></a>
<span class="name">
<span class="modifier">Public</span>
<span ><b>getOverridable</b></span>
<a href="#getOverridable"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>getOverridable(path: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</a>)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="239"
class="link-to-prism">src/i18n/i18n.service.ts:239</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Returns an instance of <code>Overridable</code> that can be used to optionally override the value provided by <code>I18n</code></p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>path</td>
<td>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank" >string</a></code>
</td>
<td>
No
</td>
<td>
<p>looks like <code>"NOTIFICATION.CLOSE_BUTTON"</code></p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="../classes/Overridable.html" target="_self" >Overridable</a></code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="getSubject"></a>
<span class="name">
<span class="modifier">Protected</span>
<span ><b>getSubject</b></span>
<a href="#getSubject"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>getSubject(path: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</a>)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="286"
class="link-to-prism">src/i18n/i18n.service.ts:286</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Helper method that returns an observable from the internal cache based on the path</p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>path</td>
<td>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank" >string</a></code>
</td>
<td>
No
</td>
<td>
<p>looks like <code>"NOTIFICATION.CLOSE_BUTTON"</code></p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="io-description">
<b>Returns : </b> <code>Observable<string></code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="getValueFromPath"></a>
<span class="name">
<span class="modifier">Public</span>
<span ><b>getValueFromPath</b></span>
<a href="#getValueFromPath"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>getValueFromPath(path: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</a>)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="269"
class="link-to-prism">src/i18n/i18n.service.ts:269</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Trys to resolve a value from the provided path.</p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>path</td>
<td>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank" >string</a></code>
</td>
<td>
No
</td>
<td>
<p>looks like <code>"NOTIFICATION.CLOSE_BUTTON"</code></p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="../miscellaneous/typealiases.html#TranslationStrings" target="_self" >string | TranslationStrings</a></code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="replace"></a>
<span class="name">
<span class="modifier">Public</span>
<span ><b>replace</b></span>
<a href="#replace"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>replace(subject: Observable<string>, variables: literal type)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="260"
class="link-to-prism">src/i18n/i18n.service.ts:260</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Takes the <code>Observable</code> returned from <code>i18n.get</code> and an object of variables to replace.</p>
<p>The keys specify the variable name in the string.</p>
<p>Example:</p>
<b>Example :</b><div><pre class="line-numbers"><code class="language-none">service.set({ "TEST": "{{foo}} {{bar}}" });
service.replace(service.get("TEST"), { foo: "test", bar: "asdf" })</code></pre></div><p>Produces: <code>"test asdf"</code></p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>subject</td>
<td>
<code>Observable<string></code>
</td>
<td>
No
</td>
<td>
<p>the translation to replace variables on</p>
</td>
</tr>
<tr>
<td>variables</td>
<td>
<code>literal type</code>
</td>
<td>
No
</td>
<td>
<p>object of variables to replace</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >any</a></code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="set"></a>
<span class="name">
<span class="modifier">Public</span>
<span ><b>set</b></span>
<a href="#set"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>set(strings: <a href="../undefineds/TranslationStrings.html" target="_self">TranslationStrings</a>)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="194"
class="link-to-prism">src/i18n/i18n.service.ts:194</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Set/update the translations from an object. Also notifies all participating components of the update.</p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>strings</td>
<td>
<code><a href="../miscellaneous/typealiases.html#TranslationStrings" target="_self" >TranslationStrings</a></code>
</td>
<td>
No
</td>
<td>
<p>an object of strings, should follow the same format as src/i18n/en.json</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >void</a></code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="setLocale"></a>
<span class="name">
<span class="modifier">Public</span>
<span ><b>setLocale</b></span>
<a href="#setLocale"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>setLocale(language: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</a>, strings?: <a href="../undefineds/TranslationStrings.html" target="_self">TranslationStrings</a>)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="168"
class="link-to-prism">src/i18n/i18n.service.ts:168</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Sets the locale and optionally the translation strings. Locale is used by components that
are already locale aware (datepicker for example) while the translation strings are used
for components that are not.</p>
<p>Locales set here will override locales/languages set in components</p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>language</td>
<td>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank" >string</a></code>
</td>
<td>
No
</td>
<td>
<p>an ISO 639-1 language code - <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes</a></p>
</td>
</tr>
<tr>
<td>strings</td>
<td>
<code><a href="../miscellaneous/typealiases.html#TranslationStrings" target="_self" >TranslationStrings</a></code>
</td>
<td>
Yes
</td>
<td>
<p>an object of strings, optional</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >void</a></code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
</section>
<section data-compodoc="block-properties">
<h3 id="inputs">
Properties
</h3>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="locale"></a>
<span class="name">
<span class="modifier">Protected</span>
<span ><b>locale</b></span>
<a href="#locale"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<i>Default value : </i><code>new BehaviorSubject("en")</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="157" class="link-to-prism">src/i18n/i18n.service.ts:157</a></div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="translations"></a>
<span class="name">
<span class="modifier">Protected</span>
<span ><b>translations</b></span>
<a href="#translations"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<i>Default value : </i><code>new Map()</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="155" class="link-to-prism">src/i18n/i18n.service.ts:155</a></div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="translationStrings"></a>
<span class="name">
<span class="modifier">Protected</span>
<span ><b>translationStrings</b></span>
<a href="#translationStrings"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<i>Type : </i> <code><a href="../miscellaneous/typealiases.html#TranslationStrings" target="_self" >TranslationStrings</a></code>
</td>
</tr>
<tr>
<td class="col-md-4">
<i>Default value : </i><code>EN</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="153" class="link-to-prism">src/i18n/i18n.service.ts:153</a></div>
</td>
</tr>
</tbody>
</table>
</section>
</div>
<div class="tab-pane fade tab-source-code" id="source">
<pre class="line-numbers compodoc-sourcecode"><code class="language-typescript">import { Injectable } from "@angular/core";
import {
BehaviorSubject,
Observable,
isObservable,
iif,
Subscription
} from "rxjs";
import { map } from "rxjs/operators";
import { merge } from "carbon-components-angular/utils";
import EN from "./en";
/**
* 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];
str = str.replace(new RegExp(`{{\\s*${key}\\s*}}`, "g"), value);
}
return str;
})
);
/**
* Represents an "overridable" translation value.
*
* Largely an internal usecase. There are situations where we want an `Observable` that
* can emit events from a centralized source **OR** an `Observable` that will emit events
* from a component local source. The key example being on/off text in a `Toggle` - In some cases
* we want the `Toggle` to use `I18n`s global translations, but in others we'd prefer to use a local
* override. We don't ever need to return to a non-overridden state, but we do need the ability to
* switch _to_ an overridden sate.
*/
export class Overridable {
/**
* The raw value of the translation. Defaults to the string value, but will return the value passed to `override`
*
* @readonly
*/
public get value(): string | Observable<string> {
return this._value;
}
public set value(v: string | Observable<string>) {
this.override(v);
}
/**
* The translation subject. Returns either a stream of overridden values, or our base translation values.
*
* @readonly
*/
public get subject(): Observable<string> {
/**
* since inputs are bound on template instantiation (and thusly will always have _some_ value)
* We can use a simple boolean and the `iif` function to determine which subject to return on subscription
*/
return iif(() => this.isOverridden, this.$override, this.baseTranslation);
}
/**
* Overridden value. Accessed by the readonly getter `value` and set through `override`
*/
protected _value: string | Observable<string>;
/**
* Subject of overridden values. Initialized with our default value.
*/
protected $override: BehaviorSubject<string>;
/**
* Our base non-overridden translation.
*/
protected baseTranslation: Observable<string> = this.i18n.get(this.path);
/**
* Subscription to the observable provided as an override (if any)
*/
protected subscription: Subscription;
/**
* A boolean to flip between overridden and non-overridden states.
*/
protected isOverridden = false;
constructor(protected path: string, protected i18n: I18n) {
/**
* ensure `$override` is initialized with the correct default value
* in some cases `_value` can get changed for an `Observable` before `$override` is created
*/
const value = this.i18n.getValueFromPath(this.path) as string;
this.$override = new BehaviorSubject<string>(value);
this._value = value;
}
/**
* Takes a string or an `Observable` that emits strings.
* Overrides the value provided by the `I18n` service.
*/
override(value: string | Observable<string>) {
this.isOverridden = true;
// To ensure that there are not multiple subscriptions created for the same observable, we
// unsubscribe if a subscription already exists for an observable before creating a new one.
if (this.subscription) {
this.subscription.unsubscribe();
this.subscription = null;
}
this._value = value;
if (isObservable(value)) {
this.subscription = value.subscribe(v => {
this.$override.next(v);
});
} else {
this.$override.next(value);
}
}
}
/**
* An object of strings, should follow the same format as src/i18n/en.json
*/
export type TranslationStrings = {
[key: string]: string | TranslationStrings;
};
/**
* The I18n service is a minimal internal singleton 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)