@hi18n/react
Version:
Message internationalization meets immutability and type-safety - runtime for React
186 lines • 6.44 kB
TypeScript
import React from "react";
import { Book, type VocabularyBase, type TranslationId, type TranslatorObject, type MessageArguments, type InstantiateComponentTypes } from "@hi18n/core";
export { LocaleContext } from "@hi18n/react-context";
/**
* Renders the children with the specified locale.
*
* @since 0.1.0 (`@hi18n/react`)
*
* @example
* ```tsx
* ReactDOM.render(
* root,
* <LocaleProvider locales="ja">
* <Translate id="example/greeting" book={book} />
* </LocaleProvider>
* );
* ```
*/
export declare const LocaleProvider: React.FC<{
children?: React.ReactNode;
/**
* A list of locales in the order of preference.
*/
locales: string | string[];
}>;
/**
* Returns the locales from the context.
*
* @returns A list of locales in the order of preference.
*
* @since 0.1.2 (`@hi18n/react`)
*
* @example
* ```tsx
* const Greeting: React.FC = () => {
* const { t } = useI18n(book);
* return (
* <section>
* <h1>{t("example/greeting")}</h1>
* {
* messages.length > 0 &&
* <p>{t("example/messages", { count: messages.length })}</p>
* }
* </section>
* );
* };
* ```
*/
export declare function useLocales(): string[];
/**
* Retrieves translation helpers, using the locale from the context.
*
* If the catalog is not loaded yet, it suspends the component being
* rendered. This is an **experimental API** which relies on React's
* undocumented API for suspension.
* To avoid this behavior,
* initialize the Book statically or use preloadCatalog from @hi18n/core
* to ensure the catalog is loaded before using this function.
*
* @param book A "book" object containing translated messages
* @returns An object containing functions necessary for translation
*
* @since 0.1.0 (`@hi18n/react`)
*
* @example
* ```tsx
* const Greeting: React.FC = () => {
* const { t } = useI18n(book);
* return (
* <section>
* <h1>{t("example/greeting")}</h1>
* {
* messages.length > 0 &&
* <p>{t("example/messages", { count: messages.length })}</p>
* }
* </section>
* );
* };
* ```
*/
export declare function useI18n<M extends VocabularyBase>(book: Book<M>): TranslatorObject<M>;
export type BaseTranslateProps<Vocabulary extends VocabularyBase, K extends string> = {
/**
* The book to look up in for the translation.
*
* @since 0.1.0 (`@hi18n/react`)
*/
book: Book<Vocabulary>;
/**
* The translation id.
*
* @since 0.1.0 (`@hi18n/react`)
*/
id: K;
/**
* The children. hi18n searches for elements in the node and names each one in the following way:
*
* - If it has a `key` prop, use the value.
* - Otherwise, give it a number in the order of occurrence of the opening tags starting with 0.
*
* They are merged into the props as the parameters for the translation.
*
* @since 0.1.0 (`@hi18n/react`)
*/
children?: React.ReactNode | undefined;
/**
* When given, the results are wrapped in the element given.
*
* Note that you don't need to use the prop in most cases.
* You can just wrap the `<Translate>` element in whatever wrapper components.
*
* One valid use case would be to pass a component that analyzes the texts or elements within the component,
* such as one that splits texts using `Intl.Segmenter` for better word-wrapping experience.
*
* @since 0.1.2 (`@hi18n/react`)
*
* @example
* ```tsx
* <Translate book={book} id="example/greeting" renderInElement={<TextWrapper />}>
* </Translate>
* ```
*/
renderInElement?: React.ReactElement | undefined;
};
export type TranslateProps<M extends VocabularyBase, K extends keyof M & string> = BaseTranslateProps<M, K> & PartialForComponents<MessageArguments<M[K], React.ReactElement>>;
type PartialForComponents<T> = Partial<T> & Omit<T, ComponentKeys<T>>;
type ComponentKeys<T, K extends keyof T = keyof T> = K extends unknown ? T[K] extends React.ReactElement ? K : never : never;
/**
* Renders the translated message, possibly interleaved with the elements you provide.
*
* If the catalog is not loaded yet, it suspends the component being
* rendered. This is an **experimental API** which relies on React's
* undocumented API for suspension.
* To avoid this behavior,
* initialize the Book statically or use preloadCatalog from @hi18n/core
* to ensure the catalog is loaded before rendering this component.
*
* @since 0.1.0 (`@hi18n/react`)
*
* @example
* ```tsx
* <Translate id="example/signin" book={book}>
* {
* // These elements are inserted into the translation.
* }
* <a href="" />
* <a href="" />
* </Translate>
* ```
*
* @example You can add a placeholder for readability.
* ```tsx
* <Translate id="example/signin" book={book}>
* You need to <a href="">sign in</a> or <a href="">sign up</a> to continue.
* </Translate>
* ```
*
* @example Naming the elements
* ```tsx
* <Translate id="example/signin" book={book}>
* <a key="signin" href="" />
* <a key="signup" href="" />
* </Translate>
* ```
*
* @example to supply non-component parameters, you can:
* ```tsx
* <Translate id="example/greeting" book={book} name={name} />
* ```
*
* This is almost equivalent to the following:
* ```tsx
* const { t } = useI18n(book);
* return t("example/greeting", { name });
* ```
*/
export declare function Translate<M extends VocabularyBase, K extends string & keyof M>(props: TranslateProps<M, K>): React.ReactElement | null;
export declare namespace Translate {
function Dynamic<Vocabulary extends VocabularyBase, Args = {}>(props: DynamicTranslateProps<Vocabulary, Args>): React.ReactElement | null;
function Todo<Vocabulary extends VocabularyBase>(props: TodoTranslateProps<Vocabulary>): React.ReactElement | null;
}
export type DynamicTranslateProps<Vocabulary extends VocabularyBase, Args> = BaseTranslateProps<Vocabulary, TranslationId<Vocabulary, Args>> & PartialForComponents<InstantiateComponentTypes<Args, React.ReactElement>>;
export type TodoTranslateProps<Vocabulary extends VocabularyBase> = BaseTranslateProps<Vocabulary, string> & {
[key: string]: unknown;
};
//# sourceMappingURL=index.d.ts.map