generaltranslation/dist/types.d.ts

A language toolkit for AI developers

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>>;
type HtmlContentPropValuesRecord = Partial<Record<(typeof HTML_CONTENT_PROPS)[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 maxChars - The maxChars of the request.
 * @param hash - The hash of the request.
 */
type EntryMetadata = {
    context?: string;
    id?: string;
    maxChars?: number;
    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 HashMetadata = {
    context?: string;
    id?: string;
    maxChars?: number;
    dataFormat: DataFormat;
};

type TranslationStatusResult = {
    count: number;
    availableLocales: string[];
    locales: string[];
    localesWaitingForApproval: any[];
};

type FileTranslationQuery = {
    versionId: string;
    fileName?: string;
    fileId?: string;
    locale: string;
};
type CheckFileTranslationsOptions = {
    timeout?: number;
};

type FileFormat = 'GTJSON' | 'JSON' | 'YAML' | 'MDX' | 'MD' | 'TS' | 'JS' | 'HTML' | 'TXT';
/**
 * File object structure for uploading files
 * @param content - Content of the file
 * @param fileName - Unique identifier for the file (such as the file path + file name)
 * @param fileFormat - The format of the file (JSON, MDX, MD, etc.)
 * @param formatMetadata - Optional metadata for the file, specific to the format of the file
 * @param dataFormat - Optional format of the data within the file
 */
type FileToUpload = {
    content: string;
    formatMetadata?: Record<string, any>;
    incomingBranchId?: string;
    checkedOutBranchId?: string;
    locale: string;
} & Omit<FileReference, 'branchId'> & {
    branchId?: string;
};
/**
 * File object structure for referencing files
 * @param fileId - The ID of the file
 * @param versionId - The ID of the version of the file
 * @param branchId - The ID of the branch of the file
 * @param locale - The locale of the file ()
 */
type FileReference = {
    fileId: string;
    versionId: string;
    branchId: string;
    fileName: string;
    fileFormat: FileFormat;
    dataFormat?: DataFormat;
};

type DownloadFileBatchOptions = {
    timeout?: number;
};
type DownloadedFile = {
    id: string;
    branchId: string;
    fileId: string;
    versionId: string;
    locale?: string;
    fileName?: string;
    data: string;
    metadata: Record<string, any>;
    fileFormat: FileFormat;
};
type DownloadFileBatchResult = {
    files: DownloadedFile[];
    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;
}))[];
/**
 * Options for enqueueing files
 * @param publish - Whether to publish the files
 * @param requireApproval - Whether to require approval for the files
 * @param description - Optional description for the project
 * @param sourceLocale - The project's source locale
 * @param targetLocales - The locales to translate the files to
 * @param version - Optional custom version ID to specify
 * @param timeout - Optional timeout for the request
 * @param modelProvider - Optional model provider to use
 */
type EnqueueFilesOptions = {
    publish?: boolean;
    requireApproval?: boolean;
    description?: string;
    sourceLocale?: string;
    targetLocales: string[];
    version?: string;
    _versionId?: string;
    timeout?: number;
    modelProvider?: string;
    force?: boolean;
};
type EnqueueFilesResult = {
    jobData: {
        [jobId: string]: {
            sourceFileId: string;
            fileId: string;
            versionId: string;
            branchId: string;
            targetLocale: string;
            projectId: string;
            force: boolean;
            modelProvider?: string;
        };
    };
    locales: string[];
    message: string;
};

/**
 * Metadata stored alongside GTJSON file entries.
 * Keys correspond to the entry id/hash in the GTJSON body.
 */
type GTJsonFormatMetadata = Record<string, {
    context?: string;
    id?: string;
    domain?: string;
    maxChars?: number;
    dataFormat?: 'JSX' | 'ICU';
    requestVersion?: number;
    approved_at?: string | null;
    approved_by?: string | null;
    hash?: string;
    filePaths?: string[];
}>;
type FileUpload = {
    branchId?: string;
    incomingBranchId?: string;
    checkedOutBranchId?: string;
    content: string;
    fileName: string;
    fileFormat: FileFormat;
    dataFormat?: DataFormat;
    locale: string;
    formatMetadata?: GTJsonFormatMetadata;
    versionId?: string;
    fileId?: 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 BranchDataResult = {
    branches: {
        id: string;
        name: string;
    }[];
    defaultBranch: {
        id: string;
        name: string;
    } | null;
};

type BranchQuery = {
    branchNames: string[];
};

type FileDataQuery = {
    sourceFiles?: {
        fileId: string;
        versionId: string;
        branchId: string;
    }[];
    translatedFiles?: {
        fileId: string;
        versionId: string;
        branchId: string;
        locale: string;
    }[];
};
type FileDataResult = {
    sourceFiles?: {
        branchId: string;
        fileId: string;
        versionId: string;
        fileName: string;
        fileFormat: string;
        dataFormat: string | null;
        createdAt: string;
        updatedAt: string;
        approvalRequiredAt: string | null;
        publishedAt: string | null;
        locales: string[];
        sourceLocale: string;
    }[];
    translatedFiles?: {
        branchId: string;
        fileId: string;
        versionId: string;
        fileFormat: string;
        dataFormat: string | null;
        createdAt: string;
        updatedAt: string;
        approvedAt: string | null;
        publishedAt: string | null;
        completedAt: string | null;
        locale: string;
    }[];
};

type JobStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'unknown';
type CheckJobStatusResult = {
    jobId: string;
    status: JobStatus;
    error?: {
        message: string;
    };
}[];

type SubmitUserEditDiff = {
    fileName: string;
    locale: string;
    diff: string;
    branchId: string;
    versionId: string;
    fileId: string;
    localContent: string;
};
type SubmitUserEditDiffsPayload = {
    diffs: SubmitUserEditDiff[];
};

/**
 * Transformations are made from a prefix and a suffix.
 */
type Transformation = 'translate-client' | 'translate-server' | 'translate-runtime' | 'variable-variable' | 'variable-currency' | 'variable-datetime' | 'variable-number' | 'plural' | 'branch';
type TransformationPrefix = 'translate' | 'variable' | 'plural' | 'branch' | 'fragment';
type VariableTransformationSuffix = 'variable' | 'number' | 'datetime' | 'currency';

/**
 * @deprecated Use {@link Content} instead.
 */
type _Content = string | Array<string | Variable>;

type Metadata = {
    maxChars?: number;
    context?: string;
    id?: string;
    sourceLocale?: string;
    actionType?: 'standard' | 'fast' | string;
    filePaths?: string[];
    [key: string]: any;
};
type FormatVariables = Record<string, string | number | boolean | null | undefined | Date>;
/**
 * @deprecated This type is deprecated and will be removed in a future version.
 */
type Update = {
    type: 'content';
    data: {
        source: _Content;
        metadata: Metadata;
    };
} | {
    type: 'jsx';
    data: {
        source: JsxChildren;
        metadata: Metadata;
    };
};
/**
 * @deprecated This type is deprecated and will be removed in a future version.
 */
type Request = {
    type: 'content';
    data: {
        source: _Content;
        targetLocale: string;
        metadata: Metadata;
    };
} | {
    type: 'jsx';
    data: {
        source: JsxChildren;
        targetLocale: string;
        metadata: Metadata;
    };
};
/**
 * @deprecated Use {@link TranslationResult} instead.
 */
type ContentTranslationResult = {
    translation: _Content;
    locale: string;
    reference?: {
        id: string;
        key: string;
    };
};
/**
 * @deprecated Use {@link TranslationResult} instead.
 */
type IcuTranslationResult = {
    translation: string;
    locale: string;
    reference?: {
        id: string;
        key: string;
    };
};
/**
 * @deprecated Use {@link TranslationResult} instead.
 */
type JsxTranslationResult = {
    translation: JsxChildren;
    locale: string;
    reference?: {
        id: string;
        key: string;
    };
};

/**
 * TranslationRequestConfig is used to configure the translation request.
 *
 * @param projectId - The project id of the translation request.
 * @param baseUrl - The base url of the translation request.
 * @param apiKey - The api key of the translation request.
 */
type TranslationRequestConfig = {
    projectId: string;
    baseUrl?: string;
    apiKey?: string;
};

export { HTML_CONTENT_PROPS };
export type { BranchDataResult, BranchQuery, CheckFileTranslationsOptions, CheckJobStatusResult, Content, ContentTranslationResult, CustomMapping, DataFormat, DownloadFileBatchOptions, DownloadFileBatchResult, DownloadFileOptions, DownloadedFile, EnqueueEntriesOptions, EnqueueEntriesResult, EnqueueFilesOptions, EnqueueFilesResult, Entry, ActionType as EntryActionType, EntryMetadata, FetchTranslationsOptions, FetchTranslationsResult, FileDataQuery, FileDataResult, FileFormat, FileReference, FileToUpload, FileTranslationQuery, FileUpload, FormatVariables, GTProp, HashMetadata, HtmlContentPropKeysRecord, HtmlContentPropValuesRecord, I18nextMessage, IcuMessage, IcuTranslationResult, JobStatus, JsxChild, JsxChildren, JsxElement, JsxTranslationResult, LocaleProperties, Metadata, Request, RetrievedTranslations, SubmitUserEditDiff, SubmitUserEditDiffsPayload, Transformation, TransformationPrefix, TranslateManyResult, TranslationError, TranslationRequestConfig, TranslationResult, TranslationResultReference, TranslationStatusResult, Update, Updates, Variable, VariableTransformationSuffix, VariableType, _Content };