generaltranslation 7.6.3 → 7.6.4-alpha.2

package/dist/index.d.ts

@@ -1,15 +1,373 @@
-import { CustomMapping, FormatVariables, I18nextMessage, IcuMessage, TranslateManyResult, TranslationError, TranslationResult, Updates, EnqueueEntriesOptions, EnqueueEntriesResult, EnqueueFilesResult, CheckFileTranslationsOptions, CheckFileTranslationsResult, DownloadFileBatchOptions, DownloadFileBatchResult, FetchTranslationsOptions, FetchTranslationsResult, DownloadFileOptions, EntryMetadata, Entry } from './types';
-import { LocaleProperties } from './locales/getLocaleProperties';
-import { JsxChildren } from './internal';
-import { SetupProjectResult } from './translate/setupProject';
-import { CheckSetupStatusResult } from './translate/checkSetupStatus';
-import { ShouldSetupProjectResult } from './translate/shouldSetupProject';
-import { EnqueueOptions } from './translate/enqueueFiles';
-import { FileQuery, FileQueryResult, FileTranslationQuery } from './types-dir/checkFileTranslations';
-import { CheckTranslationStatusOptions, TranslationStatusResult } from './types-dir/translationStatus';
-import { CustomRegionMapping } from './locales/getRegionProperties';
-import { FileUpload, FileUploadRef, UploadFilesOptions, UploadFilesResponse } from './types-dir/uploadFiles';
-import { ProjectData } from './types-dir/project';
+type CustomMapping = Record<string, string | Partial<LocaleProperties>>;
+
+type LocaleProperties = {
+    code: string;
+    name: string;
+    nativeName: string;
+    languageCode: string;
+    languageName: string;
+    nativeLanguageName: string;
+    nameWithRegionCode: string;
+    nativeNameWithRegionCode: string;
+    regionCode: string;
+    regionName: string;
+    nativeRegionName: string;
+    scriptCode: string;
+    scriptName: string;
+    nativeScriptName: string;
+    maximizedCode: string;
+    maximizedName: string;
+    nativeMaximizedName: string;
+    minimizedCode: string;
+    minimizedName: string;
+    nativeMinimizedName: string;
+    emoji: string;
+};
+
+type VariableType = 'v' | 'n' | 'd' | 'c';
+/**
+ * Variables are used to store the variable name and type.
+ */
+type Variable = {
+    k: string;
+    i?: number;
+    v?: VariableType;
+};
+
+/**
+ * Map of data-_gt properties to their corresponding React props
+ */
+declare const HTML_CONTENT_PROPS: {
+    readonly pl: "placeholder";
+    readonly ti: "title";
+    readonly alt: "alt";
+    readonly arl: "aria-label";
+    readonly arb: "aria-labelledby";
+    readonly ard: "aria-describedby";
+};
+type HtmlContentPropKeysRecord = Partial<Record<keyof typeof HTML_CONTENT_PROPS, string>>;
+/**
+ * GTProp is an internal property used to contain data for translating and rendering elements.
+ * note, transformations are only read on the server side if they are 'plural' or 'branch'
+ */
+type GTProp = {
+    b?: Record<string, JsxChildren>;
+    t?: 'p' | 'b';
+} & HtmlContentPropKeysRecord;
+type JsxElement = {
+    t?: string;
+    i?: number;
+    d?: GTProp;
+    c?: JsxChildren;
+};
+type JsxChild = string | JsxElement | Variable;
+/**
+ * The format of the content
+ */
+type DataFormat = 'JSX' | 'ICU' | 'I18NEXT';
+/**
+ * A content type representing JSX, ICU, and I18next messages
+ */
+type Content = JsxChildren | IcuMessage | I18nextMessage;
+/**
+ * A content type representing JSX elements
+ */
+type JsxChildren = JsxChild | JsxChild[];
+/**
+ * A content type representing ICU messages
+ */
+type IcuMessage = string;
+/**
+ * A content type representing I18next messages
+ */
+type I18nextMessage = string;
+
+/**
+ * ActionType is the type of action to perform on the request.
+ *
+ * @param standard - The standard action type (standard model).
+ * @param fast - The fast action type (mini model).
+ * @param string - Other model
+ */
+type ActionType = 'standard' | 'fast' | string;
+/**
+ * EntryMetadata is the metadata for a GTRequest.
+ *
+ * @param context - The context of the request.
+ * @param id - The id of the request.
+ * @param hash - The hash of the request.
+ */
+type EntryMetadata = {
+    context?: string;
+    id?: string;
+    hash?: string;
+    dataFormat?: DataFormat;
+    sourceLocale?: string;
+    actionType?: ActionType;
+    timeout?: number;
+    regionCode?: string;
+    scriptCode?: string;
+};
+/**
+ * GTRequest is a translation request object for {@link JsxChildren} | {@link IcuMessage} | {@link I18nextMessage}
+ *
+ * @param source - The source content to translate.
+ * @param targetLocale - The target locale to translate to.
+ * @param metadata - The metadata for the request.
+ */
+type Entry = {
+    source: Content;
+    targetLocale?: string;
+    metadata?: EntryMetadata;
+};
+
+type TranslationStatusResult = {
+    count: number;
+    availableLocales: string[];
+    locales: string[];
+    localesWaitingForApproval: any[];
+};
+type CheckTranslationStatusOptions = {
+    timeout?: number;
+};
+
+type FileFormat = 'GTJSON' | 'JSON' | 'YAML' | 'MDX' | 'MD' | 'TS' | 'JS' | 'HTML';
+type CompletedFileTranslationData = {
+    locale: string;
+    metadata: any;
+    fileId: string;
+    fileName: string;
+    versionId: string;
+    id: string;
+    isReady: boolean;
+    downloadUrl: string;
+};
+
+type FileTranslationQuery = {
+    versionId: string;
+    fileName?: string;
+    fileId?: string;
+    locale: string;
+};
+type CheckFileTranslationsOptions = {
+    timeout?: number;
+};
+type CheckFileTranslationsResult = {
+    translations: CompletedFileTranslationData[];
+};
+type FileQuery = {
+    fileId: string;
+    versionId?: string;
+};
+type FileQueryResult = {
+    sourceFile: {
+        id: string;
+        fileId: string;
+        versionId: string;
+        sourceLocale: string;
+        fileName: string;
+        fileFormat: string;
+        dataFormat: string | null;
+        createdAt: string;
+        updatedAt: string;
+        approvalRequiredAt: string | null;
+        locales: string[];
+    };
+    translations: {
+        locale: string;
+        completedAt: string | null;
+        approvedAt: string | null;
+        publishedAt: string | null;
+        createdAt: string | null;
+        updatedAt: string | null;
+    }[];
+};
+
+type DownloadFileBatchOptions = {
+    timeout?: number;
+};
+type File = {
+    id: string;
+    fileName: string;
+    data: string;
+    metadata: any;
+};
+type DownloadFileBatchResult = {
+    files: File[];
+    count: number;
+};
+
+type FetchTranslationsOptions = {
+    timeout?: number;
+};
+type RetrievedTranslation = {
+    locale: string;
+    translation: any;
+};
+type RetrievedTranslations = RetrievedTranslation[];
+type FetchTranslationsResult = {
+    translations: RetrievedTranslations;
+};
+
+type Updates = ({
+    metadata: Record<string, any>;
+} & ({
+    dataFormat: 'JSX';
+    source: JsxChildren;
+} | {
+    dataFormat: 'ICU';
+    source: string;
+} | {
+    dataFormat: 'I18NEXT';
+    source: string;
+}))[];
+type EnqueueFilesResult = {
+    translations: CompletedFileTranslationData[];
+    data: Record<string, {
+        fileName: string;
+        versionId: string;
+    }>;
+    locales: string[];
+    message: string;
+};
+
+type EnqueueEntriesOptions = {
+    timeout?: number;
+    sourceLocale?: string;
+    targetLocales?: string[];
+    dataFormat?: DataFormat;
+    version?: string;
+    description?: string;
+    requireApproval?: boolean;
+    modelProvider?: string;
+};
+type EnqueueEntriesResult = {
+    versionId: string;
+    locales: string[];
+    message: string;
+    projectSettings: {
+        cdnEnabled: boolean;
+        requireApproval: boolean;
+    };
+};
+
+type DownloadFileOptions = {
+    timeout?: number;
+};
+
+/**
+ * TranslationResultReference is used to store the reference for a translation result.
+ */
+type TranslationResultReference = {
+    id?: string;
+    hash: string;
+};
+/**
+ * TypedResult is a union type that represents the different types of translations that can be returned.
+ */
+type TypedResult = {
+    translation: JsxChildren;
+    dataFormat: 'JSX';
+} | {
+    translation: I18nextMessage | IcuMessage;
+    dataFormat: 'ICU' | 'I18NEXT';
+};
+/**
+ * RequestError is a type that represents an error that occurred during a translation request.
+ */
+type TranslationError = {
+    error: string;
+    code: number;
+    reference?: TranslationResultReference;
+};
+/**
+ * RequestSuccess is a type that represents a successful translation request.
+ */
+type RequestSuccess = TypedResult & {
+    locale: string;
+    reference: TranslationResultReference;
+};
+type TranslationResult = RequestSuccess | TranslationError;
+
+/**
+ * BatchTranslationResult is the result of a batch translation request.
+ */
+type TranslateManyResult = Array<TranslationResult>;
+
+type FormatVariables = Record<string, string | number | boolean | null | undefined | Date>;
+
+type SetupProjectResult = {
+    setupJobId: string;
+    status: 'queued';
+};
+
+type SetupJobStatus = 'queued' | 'processing' | 'completed' | 'failed';
+type CheckSetupStatusResult = {
+    jobId: string;
+    status: SetupJobStatus;
+    error?: {
+        message: string;
+    };
+};
+
+type ShouldSetupProjectResult = {
+    shouldSetupProject: boolean;
+};
+
+type EnqueueOptions = {
+    sourceLocale: string;
+    targetLocales: string[];
+    publish?: boolean;
+    requireApproval?: boolean;
+    modelProvider?: string;
+    force?: boolean;
+    timeout?: number;
+};
+
+type CustomRegionMapping = {
+    [region: string]: {
+        name?: string;
+        emoji?: string;
+        locale?: string;
+    };
+};
+
+type FileUpload = {
+    content: string;
+    fileName: string;
+    fileFormat: FileFormat;
+    dataFormat?: DataFormat;
+    locale: string;
+    versionId?: string;
+    fileId?: string;
+};
+type FileUploadRef = {
+    fileId: string;
+    versionId: string;
+    fileName: string;
+    fileFormat: FileFormat;
+    dataFormat?: DataFormat;
+    locale?: string;
+};
+type UploadFilesOptions = {
+    sourceLocale: string;
+    modelProvider?: string;
+    timeout?: number;
+};
+type UploadFilesResponse = {
+    uploadedFiles: FileUploadRef[];
+    count: number;
+    message: string;
+};
+
+type ProjectData = {
+    id: string;
+    name: string;
+    orgId: string;
+    defaultLocale: string;
+    currentLocales: string[];
+};
+
 /**
  * Type representing the constructor parameters for the GT class.
  * @typedef {Object} GTConstructorParams
@@ -46,7 +404,7 @@ type GTConstructorParams = {
  *   locales: ['en-US', 'es-ES', 'fr-FR']
  * });
  */
-export declare class GT {
+declare class GT {
     /** Base URL for the translation service API */
     baseUrl?: string;
     /** Project ID for the translation service */
@@ -781,7 +1139,7 @@ export declare class GT {
  * formatMessage('Hello {name}', { name: 'John' }, { locales: ['fr'] });
  * // Returns: "Bonjour John"
  */
-export declare function formatMessage(message: string, options?: {
+declare function formatMessage(message: string, options?: {
     locales?: string | string[];
     variables?: FormatVariables;
 }): string;
@@ -793,7 +1151,7 @@ export declare function formatMessage(message: string, options?: {
  * @param {string | string[]} [params.options.locales] - The locales to use for formatting.
  * @returns {string} The formatted number.
  */
-export declare function formatNum(number: number, options: {
+declare function formatNum(number: number, options: {
     locales: string | string[];
 } & Intl.NumberFormatOptions): string;
 /**
@@ -804,7 +1162,7 @@ export declare function formatNum(number: number, options: {
  * @param {string | string[]} [params.options.locales] - The languages to use for formatting.
  * @returns {string} The formatted date.
  */
-export declare function formatDateTime(date: Date, options?: {
+declare function formatDateTime(date: Date, options?: {
     locales?: string | string[];
 } & Intl.DateTimeFormatOptions): string;
 /**
@@ -816,7 +1174,7 @@ export declare function formatDateTime(date: Date, options?: {
  * @param {string | string[]} [params.options.locales] - The locale codes to use for formatting.
  * @returns {string} The formatted currency value.
  */
-export declare function formatCurrency(value: number, currency: string, options: {
+declare function formatCurrency(value: number, currency: string, options: {
     locales: string | string[];
 } & Intl.NumberFormatOptions): string;
 /**
@@ -827,7 +1185,7 @@ export declare function formatCurrency(value: number, currency: string, options:
  * @param {string | string[]} [params.options.locales] - The locales to use for formatting.
  * @returns {string} The formatted list.
  */
-export declare function formatList(array: Array<string | number>, options: {
+declare function formatList(array: Array<string | number>, options: {
     locales: string | string[];
 } & Intl.ListFormatOptions): string;
 /**
@@ -839,7 +1197,7 @@ export declare function formatList(array: Array<string | number>, options: {
  * @param {string | string[]} [params.options.locales] - The locales to use for formatting.
  * @returns {string} The formatted relative time string.
  */
-export declare function formatRelativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options: {
+declare function formatRelativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options: {
     locales: string | string[];
 } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>): string;
 /**
@@ -850,7 +1208,7 @@ export declare function formatRelativeTime(value: number, unit: Intl.RelativeTim
  * @param {CustomMapping} [customMapping] - A custom mapping of locale codes to their names.
  * @returns {string} The display name corresponding to the code.
  */
-export declare function getLocaleName(locale: string, defaultLocale?: string, customMapping?: CustomMapping): string;
+declare function getLocaleName(locale: string, defaultLocale?: string, customMapping?: CustomMapping): string;
 /**
  * Retrieves an emoji based on a given locale code, taking into account region, language, and specific exceptions.
  *
@@ -860,7 +1218,7 @@ export declare function getLocaleName(locale: string, defaultLocale?: string, cu
  * @param {CustomMapping} [customMapping] - A custom mapping of locale codes to their names.
  * @returns The emoji representing the locale or its region, or a default emoji if no specific match is found.
  */
-export declare function getLocaleEmoji(locale: string, customMapping?: CustomMapping): string;
+declare function getLocaleEmoji(locale: string, customMapping?: CustomMapping): string;
 /**
  * Generates linguistic details for a given locale code.
  *
@@ -895,7 +1253,7 @@ export declare function getLocaleEmoji(locale: string, customMapping?: CustomMap
  * @property {string} nativeMinimizedName - Minimized language name in the native language, e.g., "Österreichisches Deutsch".
  * @property {string} emoji - The emoji associated with the locale's region, if applicable.
  */
-export declare function getLocaleProperties(locale: string, defaultLocale?: string, customMapping?: CustomMapping): LocaleProperties;
+declare function getLocaleProperties(locale: string, defaultLocale?: string, customMapping?: CustomMapping): LocaleProperties;
 /**
  * Determines whether a translation is required based on the source and target locales.
  *
@@ -910,53 +1268,53 @@ export declare function getLocaleProperties(locale: string, defaultLocale?: stri
  *
  * @returns {boolean} - Returns `true` if translation is required, otherwise `false`.
  */
-export declare function requiresTranslation(sourceLocale: string, targetLocale: string, approvedLocales?: string[], customMapping?: CustomMapping): boolean;
+declare function requiresTranslation(sourceLocale: string, targetLocale: string, approvedLocales?: string[], customMapping?: CustomMapping): boolean;
 /**
  * Determines the best matching locale from the provided approved locales list.
  * @param {string | string[]} locales - A single locale or an array of locales sorted in preference order.
  * @param {string[]} [approvedLocales=this.locales] - An array of approved locales, also sorted by preference.
  * @returns {string | undefined} - The best matching locale from the approvedLocales list, or undefined if no match is found.
  */
-export declare function determineLocale(locales: string | string[], approvedLocales?: string[] | undefined, customMapping?: CustomMapping | undefined): string | undefined;
+declare function determineLocale(locales: string | string[], approvedLocales?: string[] | undefined, customMapping?: CustomMapping | undefined): string | undefined;
 /**
  * Get the text direction for a given locale code using the Intl.Locale API.
  *
  * @param {string} locale - A BCP-47 locale code.
  * @returns {string} - 'rtl' if the locale is right-to-left, otherwise 'ltr'.
  */
-export declare function getLocaleDirection(locale: string): 'ltr' | 'rtl';
+declare function getLocaleDirection(locale: string): 'ltr' | 'rtl';
 /**
  * Checks if a given BCP 47 locale code is valid.
  * @param {string} locale - The BCP 47 locale code to validate.
  * @param {CustomMapping} [customMapping] - The custom mapping to use for validation.
  * @returns {boolean} True if the BCP 47 code is valid, false otherwise.
  */
-export declare function isValidLocale(locale: string, customMapping?: CustomMapping): boolean;
+declare function isValidLocale(locale: string, customMapping?: CustomMapping): boolean;
 /**
  * Resolves the alias locale for a given locale.
  * @param {string} locale - The locale to resolve the alias locale for
  * @param {CustomMapping} [customMapping] - The custom mapping to use for resolving the alias locale
  * @returns {string} The alias locale
  */
-export declare function resolveAliasLocale(locale: string, customMapping?: CustomMapping): string;
+declare function resolveAliasLocale(locale: string, customMapping?: CustomMapping): string;
 /**
  * Standardizes a BCP 47 locale code to ensure correct formatting.
  * @param {string} locale - The BCP 47 locale code to standardize.
  * @returns {string} The standardized BCP 47 locale code or an empty string if it is an invalid code.
  */
-export declare function standardizeLocale(locale: string): string;
+declare function standardizeLocale(locale: string): string;
 /**
  * Checks if multiple BCP 47 locale codes represent the same dialect.
  * @param {string[]} locales - The BCP 47 locale codes to compare.
  * @returns {boolean} True if all BCP 47 codes represent the same dialect, false otherwise.
  */
-export declare function isSameDialect(...locales: (string | string[])[]): boolean;
+declare function isSameDialect(...locales: (string | string[])[]): boolean;
 /**
  * Checks if multiple BCP 47 locale codes represent the same language.
  * @param {string[]} locales - The BCP 47 locale codes to compare.
  * @returns {boolean} True if all BCP 47 codes represent the same language, false otherwise.
  */
-export declare function isSameLanguage(...locales: (string | string[])[]): boolean;
+declare function isSameLanguage(...locales: (string | string[])[]): boolean;
 /**
  * Checks if a locale is a superset of another locale.
  * A subLocale is a subset of superLocale if it is an extension of superLocale or are otherwise identical.
@@ -965,5 +1323,6 @@ export declare function isSameLanguage(...locales: (string | string[])[]): boole
  * @param {string} subLocale - The locale to check if it is a subset of the other locale.
  * @returns {boolean} True if the first locale is a superset of the second locale, false otherwise.
  */
-export declare function isSupersetLocale(superLocale: string, subLocale: string): boolean;
-export {};
+declare function isSupersetLocale(superLocale: string, subLocale: string): boolean;
+
+export { GT, determineLocale, formatCurrency, formatDateTime, formatList, formatMessage, formatNum, formatRelativeTime, getLocaleDirection, getLocaleEmoji, getLocaleName, getLocaleProperties, isSameDialect, isSameLanguage, isSupersetLocale, isValidLocale, requiresTranslation, resolveAliasLocale, standardizeLocale };