carbon-components-angular
Version:
Next generation components
321 lines (317 loc) • 10.3 kB
TypeScript
/**
*
* carbon-angular v0.0.0 | i18n.service.d.ts
*
* Copyright 2014, 2024 IBM
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { BehaviorSubject, Observable, Subscription } from "rxjs";
import * as i0 from "@angular/core";
/**
* 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 declare const replace: (subject: any, variables: any) => any;
/**
* 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 declare class Overridable {
protected path: string;
protected i18n: I18n;
/**
* The raw value of the translation. Defaults to the string value, but will return the value passed to `override`
*
* @readonly
*/
get value(): string | Observable<string>;
set value(v: string | Observable<string>);
/**
* The translation subject. Returns either a stream of overridden values, or our base translation values.
*
* @readonly
*/
get subject(): Observable<string>;
/**
* 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>;
/**
* 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: boolean;
constructor(path: string, i18n: I18n);
/**
* Takes a string or an `Observable` that emits strings.
* Overrides the value provided by the `I18n` service.
*/
override(value: string | Observable<string>): void;
}
/**
* An object of strings, should follow the same format as src/i18n/en.json
*/
export declare type TranslationStrings = {
[key: string]: string;
};
/**
* 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)
*
*/
export declare class I18n {
protected translationStrings: {
BREADCRUMB: {
LABEL: string;
};
CODE_SNIPPET: {
CODE_SNIPPET_TEXT: string;
SHOW_MORE: string;
SHOW_LESS: string;
SHOW_MORE_ICON: string;
COPY_CODE: string;
COPIED: string;
};
COMBOBOX: {
PLACEHOLDER: string;
CLEAR_SELECTIONS: string;
CLEAR_SELECTED: string;
A11Y: {
OPEN_MENU: string;
CLOSE_MENU: string;
CLEAR_SELECTIONS: string;
CLEAR_SELECTED: string;
};
};
DROPDOWN: {
OPEN: string;
SELECTED: string;
CLEAR: string;
FILTER: {
SELECTED_ONLY: string;
SEARCH: string;
NO_RESULTS: string;
RESET_SEARCH: string;
};
};
DROPDOWN_LIST: {
LABEL: string;
};
FILE_UPLOADER: {
CHECKMARK: string;
OPEN: string;
REMOVE_BUTTON: string;
};
LOADING: {
TITLE: string;
};
MODAL: {
CLOSE: string;
};
NOTIFICATION: {
CLOSE_BUTTON: string;
};
NUMBER: {
INCREMENT: string;
DECREMENT: string;
};
OVERFLOW_MENU: {
OVERFLOW: string;
};
SEARCH: {
LABEL: string;
PLACEHOLDER: string;
CLEAR_BUTTON: string;
};
PAGINATION: {
ITEMS_PER_PAGE: string;
OPEN_LIST_OF_OPTIONS: string;
BACKWARD: string;
FORWARD: string;
TOTAL_ITEMS_UNKNOWN: string;
TOTAL_ITEMS: string;
TOTAL_ITEM: string;
PAGE: string;
OF_LAST_PAGES: string;
OF_LAST_PAGE: string;
NEXT: string;
PREVIOUS: string;
SELECT_ARIA: string;
};
PROGRESS_INDICATOR: {
CURRENT: string;
INCOMPLETE: string;
COMPLETE: string;
INVALID: string;
};
TABLE: {
FILTER: string;
END_OF_DATA: string;
SCROLL_TOP: string;
CHECKBOX_HEADER: string;
CHECKBOX_ROW: string;
EXPAND_BUTTON: string;
SORT_DESCENDING: string;
SORT_ASCENDING: string;
ROW: string;
};
TABLE_TOOLBAR: {
ACTION_BAR: string;
BATCH_TEXT: string;
BATCH_TEXT_SINGLE: string;
BATCH_TEXT_MULTIPLE: string;
CANCEL: string;
};
TABS: {
BUTTON_ARIA_LEFT: string;
BUTTON_ARIA_RIGHT: string;
HEADER_ARIA_LABEL: string;
};
TILES: {
TILE: string;
EXPAND: string;
COLLAPSE: string;
};
TOGGLE: {
OFF: string;
ON: string;
};
UI_SHELL: {
SKIP_TO: string;
HEADER: {
OPEN_MENU: string;
CLOSE_MENU: string;
};
SIDE_NAV: {
TOGGLE_OPEN: string;
TOGGLE_CLOSE: string;
};
};
};
protected translations: Map<any, any>;
protected locale: BehaviorSubject<string>;
/**
* 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.
*
* Locales set here will override locales/languages set in components
* @param language an ISO 639-1 language code - https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
* @param strings an object of strings, optional
*/
setLocale(language: string, strings?: TranslationStrings): void;
/**
* Returns the current locale
*/
getLocale(): string;
/**
* Returns an observable that resolves to the current locale, and will update when changed
*/
getLocaleObservable(): Observable<string>;
/**
* 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
*/
set(strings: TranslationStrings): void;
/**
* 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"`
*/
get(path?: string): any;
/**
* Returns all descendents of some path fragment as an object.
*
* @param partialPath a path fragment, for example `"NOTIFICATION"`
*/
getMultiple(partialPath: string): {
[key: string]: Observable<string>;
};
/**
* Returns an instance of `Overridable` that can be used to optionally override the value provided by `I18n`
* @param path looks like `"NOTIFICATION.CLOSE_BUTTON"`
*/
getOverridable(path: string): Overridable;
/**
* 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
*/
replace(subject: Observable<string>, variables: {
[key: string]: string;
}): any;
/**
* Trys to resolve a value from the provided path.
*
* @param path looks like `"NOTIFICATION.CLOSE_BUTTON"`
*/
getValueFromPath(path: any): string | {
[key: string]: string;
};
/**
* Helper method that returns an observable from the internal cache based on the path
*
* @param path looks like `"NOTIFICATION.CLOSE_BUTTON"`
*/
protected getSubject(path: string): Observable<string>;
static ɵfac: i0.ɵɵFactoryDeclaration<I18n, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<I18n>;
}