studiocms/dist/virtuals/i18n/server.d.ts

Astro Native CMS for AstroDB. Built from the ground up by the Astro community.

/**
 * This module handles internationalization (i18n) for the StudioCMS application on the server side.
 *
 * It provides utilities for loading and managing translation files, as well as functions for
 * retrieving translated strings based on the current language context.
 *
 * If you are interested in contributing to the translation effort, please visit our Crowdin project:
 * https://crowdin.com/project/studiocms or submit a pull request to the `translations` folder:
 * `packages/studiocms/src/virtuals/i18n/translations/` on https://github.com/withstudiocms/studiocms
 */
import type { AstroGlobal } from 'astro';
import { defaultLang } from './config.js';
export { defaultLang };
/**
 * The UI translations available in the StudioCMS app.
 */
declare const uiTranslations: import("./config.js").ServerUiTranslations;
/**
 * Represents the type of UI translations.
 * This type is derived from the structure of the `uiTranslations` object.
 */
export type UiTranslations = typeof uiTranslations;
/**
 * Represents the keys of the UiTranslations type.
 * This type is used to define the possible keys for UI language translations.
 */
export type UiLanguageKeys = keyof UiTranslations;
/**
 * Represents the keys of the UI component translations for the 'en' locale.
 * This type is derived from the 'translations' property of the 'UiTranslations' interface
 * for the 'en' locale (Source of truth), ensuring that only valid translation keys are used.
 */
export type UiComponentKeys = keyof UiTranslations['en']['translations'];
/**
 * Represents the translation type for a specific UI component key (`T`)
 * within a given language key (`L`) from the `uiTranslations` object.
 *
 * @typeParam L - The language key, constrained to `UiLanguageKeys`.
 * @typeParam T - The UI component key, constrained to `UiComponentKeys`.
 *
 * @example
 * // Get the translation type for the 'button' component in 'en' language:
 * type ButtonTranslation = UiTranslationComponent<'en', 'button'>;
 */
type UiTranslationComponent<L extends UiLanguageKeys, T extends UiComponentKeys> = (typeof uiTranslations)[L]['translations'][T];
/**
 * Represents the set of valid translation keys for a specific UI component and language.
 *
 * @typeParam L - The type representing the available UI language keys.
 * @typeParam T - The type representing the available UI component keys.
 *
 * This type resolves to the union of property names (keys) of the translation object
 * for the given language (`L`) and component (`T`), as defined by `UiTranslationComponent`.
 */
type UiTranslationComponentKey<L extends UiLanguageKeys, T extends UiComponentKeys> = keyof UiTranslationComponent<L, T>;
/**
 * Retrieves a translation function for a given language and component.
 *
 * @param lang - The language key to use for translations.
 * @param component - The component key to use for translations.
 * @returns A function that takes a translation key and returns the corresponding translated string.
 */
export declare function useTranslations<L extends UiLanguageKeys, T extends UiComponentKeys>(lang: L, component: T): (key: UiTranslationComponentKey<L, T>) => string;
/**
 * Returns a function that translates a given path based on the provided language.
 *
 * @param lang - The language key to be used for translation.
 * @returns A function that takes a path and an optional language key, and returns the translated path.
 * If the language key is not provided, the default language key is used.
 * If the language is the default language and `showDefaultLang` is false, the original path is returned.
 * Otherwise, the path is prefixed with the language key.
 */
export declare function useTranslatedPath(lang: UiLanguageKeys): (path: string, l?: UiLanguageKeys) => string;
/**
 * Extracts the language key from the given URL's pathname.
 *
 * @param url - The URL object from which to extract the language key.
 * @returns The language key if it exists in the `uiTranslations`, otherwise returns the default language key.
 */
export declare function getLangFromUrl(url: URL): string;
/**
 * Retrieves the current URL path, adjusting for language settings.
 *
 * This function checks if the URL path includes '/_server-islands'. If it does,
 * it extracts the referer URL from the request headers and determines the current
 * language from that URL. If the current language is the default language, it returns
 * the pathname as is. Otherwise, it replaces the language segment in the pathname with '/'.
 *
 * If the URL path does not include '/_server-islands', it uses the Astro URL directly
 * to determine the current language and adjust the pathname accordingly.
 *
 * @param {AstroGlobal} Astro - The global Astro object containing URL and request information.
 */
export declare function getCurrentURLPath(Astro: AstroGlobal): string;
/**
 * Function to switch the language of the current page.
 *
 * @param {AstroGlobal} Astro - The global Astro object.
 */
export declare function switchLanguage(Astro: AstroGlobal): (languageKey: UiLanguageKeys) => string;
/**
 * Example of how to use this i18n utils on a Static page
 *
 * @example
 * ```ts
 * export async function getStaticPaths() {
 *	const paths = staticPaths();
 *	return paths;
 * }
 * ```
 *
 * If the default language is hidden, the paths for the default language will be generated without the language prefix while all extra languages will have the prefix. (e.g. When `showDefaultLang` is false: `/en/page` will be `/page` and spanish will be `/es/page`)
 *
 * @returns An array of paths for all languages
 */
export declare const staticPaths: () => {
    params: {
        locale: string | undefined;
    };
}[];