generaltranslation 7.0.0 → 7.1.0-alpha.0

package/dist/internal.d.ts

@@ -2,8 +2,8 @@ export { defaultBaseUrl, defaultCacheUrl, defaultRuntimeApiUrl, } from './settin
 export { libraryDefaultLocale } from './settings/settings';
 export { pluralForms, isAcceptedPluralForm } from './settings/plurals';
 import _getPluralForm from './locales/getPluralForm';
-import { Content, JsxChild, JsxChildren, JsxElement } from './types';
+import { _Content, JsxChild, JsxChildren, JsxElement } from './types';
 import { LocaleProperties } from './types';
 import isVariable from './utils/isVariable';
 import { minifyVariableType } from './utils/minify';
-export { _getPluralForm as getPluralForm, JsxChildren, Content, JsxChild, JsxElement, LocaleProperties, isVariable, minifyVariableType, };
+export { _getPluralForm as getPluralForm, JsxChildren, _Content, JsxChild, JsxElement, LocaleProperties, isVariable, minifyVariableType, };

package/dist/logging/errors.d.ts

@@ -0,0 +1,10 @@
+export declare const translationTimeoutError: (timeout: number) => string;
+export declare const translationRequestFailedError: (error: string) => string;
+export declare const apiError: (status: number, statusText: string, error: string) => string;
+export declare const invalidAuthError = "GT error: Invalid authentication.";
+export declare const noTargetLocaleProvidedError: (functionName: string) => string;
+export declare const noSourceLocaleProvidedError: (functionName: string) => string;
+export declare const noProjectIdProvidedError: (functionName: string) => string;
+export declare const noApiKeyProvidedError: (functionName: string) => string;
+export declare const invalidLocaleError: (locale: string) => string;
+export declare const invalidLocalesError: (locales: string[]) => string;

package/dist/logging/logger.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Comprehensive logging system for the General Translation library
+ * Provides structured logging with multiple levels and configurable output
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'off';
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: Date;
+    context?: string;
+    metadata?: Record<string, any>;
+}
+export interface LoggerConfig {
+    /** Minimum log level to output */
+    level: LogLevel;
+    /** Whether to include timestamps in log output */
+    includeTimestamp: boolean;
+    /** Whether to include context information */
+    includeContext: boolean;
+    /** Custom prefix for all log messages */
+    prefix?: string;
+    /** Whether to output to console (default: true) */
+    enableConsole: boolean;
+    /** Custom log handlers */
+    handlers?: LogHandler[];
+}
+export interface LogHandler {
+    handle(entry: LogEntry): void;
+}
+/**
+ * Console log handler that outputs formatted messages to console
+ */
+export declare class ConsoleLogHandler implements LogHandler {
+    private config;
+    constructor(config: LoggerConfig);
+    handle(entry: LogEntry): void;
+}
+/**
+ * Main Logger class providing structured logging capabilities
+ */
+export declare class Logger {
+    private config;
+    private handlers;
+    constructor(config?: Partial<LoggerConfig>);
+    /**
+     * Add a custom log handler
+     */
+    addHandler(handler: LogHandler): void;
+    /**
+     * Remove a log handler
+     */
+    removeHandler(handler: LogHandler): void;
+    /**
+     * Update logger configuration
+     */
+    configure(config: Partial<LoggerConfig>): void;
+    /**
+     * Check if a log level should be output based on current configuration
+     */
+    private shouldLog;
+    /**
+     * Internal logging method that creates log entries and passes them to handlers
+     */
+    private log;
+    /**
+     * Log a debug message
+     * Used for detailed diagnostic information, typically of interest only when diagnosing problems
+     */
+    debug(message: string, context?: string, metadata?: Record<string, any>): void;
+    /**
+     * Log an info message
+     * Used for general information about application operation
+     */
+    info(message: string, context?: string, metadata?: Record<string, any>): void;
+    /**
+     * Log a warning message
+     * Used for potentially problematic situations that don't prevent operation
+     */
+    warn(message: string, context?: string, metadata?: Record<string, any>): void;
+    /**
+     * Log an error message
+     * Used for error events that might still allow the application to continue
+     */
+    error(message: string, context?: string, metadata?: Record<string, any>): void;
+    /**
+     * Create a child logger with a specific context
+     */
+    child(context: string): ContextLogger;
+    /**
+     * Get current logger configuration
+     */
+    getConfig(): LoggerConfig;
+}
+/**
+ * Context logger that automatically includes context information
+ */
+export declare class ContextLogger {
+    private logger;
+    private context;
+    constructor(logger: Logger, context: string);
+    debug(message: string, metadata?: Record<string, any>): void;
+    info(message: string, metadata?: Record<string, any>): void;
+    warn(message: string, metadata?: Record<string, any>): void;
+    error(message: string, metadata?: Record<string, any>): void;
+    child(childContext: string): ContextLogger;
+}
+export declare const defaultLogger: Logger;
+export declare const debug: (message: string, context?: string, metadata?: Record<string, any>) => void;
+export declare const info: (message: string, context?: string, metadata?: Record<string, any>) => void;
+export declare const warn: (message: string, context?: string, metadata?: Record<string, any>) => void;
+export declare const error: (message: string, context?: string, metadata?: Record<string, any>) => void;
+export declare const fetchLogger: ContextLogger;
+export declare const validationLogger: ContextLogger;
+export declare const formattingLogger: ContextLogger;
+export declare const localeLogger: ContextLogger;
+export declare const gtInstanceLogger: ContextLogger;
+export { Logger as GTLogger };

package/dist/logging/warnings.d.ts

@@ -0,0 +1,2 @@
+export declare const formatI18nextWarning = "Warning: formatI18next is not currently supported but will be implemented in a future version. Use _formatMessage for current ICU message format support.";
+export declare const formatJsxWarning = "Warning: formatJsx is not currently supported but will be implemented in a future version. Use _formatMessage for current ICU message format support.";

package/dist/translate/checkFileTranslations.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translate/checkTranslationStatus.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translate/downloadFile.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translate/downloadFileBatch.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translate/enqueueEntries.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translate/enqueueFiles.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translate/fetchTranslations.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translate/translate.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translate/translateMany.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translate/utils/fetchWithTimeout.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translate/utils/generateRequestHeaders.d.ts

@@ -0,0 +1,6 @@
+import { TranslationRequestConfig } from '../../types';
+export default function generateRequestHeaders(config: TranslationRequestConfig, excludeContentType?: boolean): {
+    'x-gt-project-id': string;
+    'x-gt-api-key'?: string | undefined;
+    'Content-Type'?: string | undefined;
+};

package/dist/translate/utils/handleFetchError.d.ts

@@ -0,0 +1 @@
+export default function handleFetchError(error: unknown, timeout: number): never;

package/dist/translate/utils/validateResponse.d.ts

@@ -0,0 +1 @@
+export default function validateResponse(response: Response): Promise<void>;

package/dist/types-dir/checkFileTranslations.d.ts

@@ -0,0 +1,12 @@
+import { CompletedFileTranslationData } from './file';
+export type FileTranslationQuery = {
+    versionId: string;
+    fileName: string;
+    locale: string;
+};
+export type CheckFileTranslationsOptions = {
+    timeout?: number;
+};
+export type CheckFileTranslationsResult = {
+    translations: CompletedFileTranslationData[];
+};

package/dist/types-dir/content.d.ts

@@ -0,0 +1,49 @@
+import { Variable } from './variables';
+/**
+ * Map of data-_gt properties to their corresponding React props
+ */
+export 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";
+};
+export type HtmlContentPropKeysRecord = Partial<Record<keyof typeof HTML_CONTENT_PROPS, string>>;
+export 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'
+ */
+export type GTProp = {
+    b?: Record<string, JsxChildren>;
+    t?: 'p' | 'b';
+} & HtmlContentPropKeysRecord;
+export type JsxElement = {
+    t?: string;
+    i?: number;
+    d?: GTProp;
+    c?: JsxChildren;
+};
+export type JsxChild = string | JsxElement | Variable;
+/**
+ * The format of the content
+ */
+export type DataFormat = 'JSX' | 'ICU' | 'I18NEXT';
+/**
+ * A content type representing JSX, ICU, and I18next messages
+ */
+export type Content = JsxChildren | IcuMessage | I18nextMessage;
+/**
+ * A content type representing JSX elements
+ */
+export type JsxChildren = JsxChild | JsxChild[];
+/**
+ * A content type representing ICU messages
+ */
+export type IcuMessage = string;
+/**
+ * A content type representing I18next messages
+ */
+export type I18nextMessage = string;

package/dist/types-dir/downloadFile.d.ts

@@ -0,0 +1,3 @@
+export type DownloadFileOptions = {
+    timeout?: number;
+};

package/dist/types-dir/downloadFileBatch.d.ts

@@ -0,0 +1,22 @@
+export type DownloadFileBatchOptions = {
+    timeout?: number;
+};
+export type BatchDownloadResult = {
+    translationId: string;
+    fileName?: string;
+    success: boolean;
+    content?: string;
+    contentType?: string;
+    error?: string;
+};
+type File = {
+    id: string;
+    fileName: string;
+    data: string;
+    metadata: any;
+};
+export type DownloadFileBatchResult = {
+    files: File[];
+    count: number;
+};
+export {};

package/dist/types-dir/enqueueEntries.d.ts

@@ -0,0 +1,20 @@
+import { DataFormat } from './content';
+export type { Updates } from './enqueueFiles';
+export type EnqueueEntriesOptions = {
+    timeout?: number;
+    sourceLocale?: string;
+    targetLocales?: string[];
+    dataFormat?: DataFormat;
+    version?: string;
+    description?: string;
+    requireApproval?: boolean;
+};
+export type EnqueueEntriesResult = {
+    versionId: string;
+    locales: string[];
+    message: string;
+    projectSettings: {
+        cdnEnabled: boolean;
+        requireApproval: boolean;
+    };
+};

package/dist/types-dir/enqueueFiles.d.ts

@@ -0,0 +1,45 @@
+import { DataFormat, JsxChildren } from './content';
+import { CompletedFileTranslationData, FileFormat } from './file';
+export type Updates = ({
+    metadata: Record<string, any>;
+} & ({
+    dataFormat: 'JSX';
+    source: JsxChildren;
+} | {
+    dataFormat: 'ICU';
+    source: string;
+} | {
+    dataFormat: 'I18NEXT';
+    source: string;
+}))[];
+/**
+ * File object structure for enqueueing files
+ * @param content - The content of the file
+ * @param fileName - The name of the file
+ * @param fileFormat - The format of the file (JSON, MDX, MD, etc.)
+ * @param dataFormat - The format of the data within the file
+ */
+export interface FileToTranslate {
+    content: string;
+    fileName: string;
+    fileFormat: FileFormat;
+    dataFormat?: DataFormat;
+}
+export type EnqueueFilesOptions = {
+    publish: boolean;
+    description?: string;
+    sourceLocale?: string;
+    targetLocales: string[];
+    _versionId?: string;
+    timeout?: number;
+};
+export type RequiredEnqueueFilesOptions = EnqueueFilesOptions & Required<Pick<EnqueueFilesOptions, 'sourceLocale'>>;
+export type EnqueueFilesResult = {
+    translations: CompletedFileTranslationData[];
+    data: Record<string, {
+        fileName: string;
+        versionId: string;
+    }>;
+    locales: string[];
+    message: string;
+};

package/dist/types-dir/entry.d.ts

@@ -0,0 +1,37 @@
+import { Content, DataFormat } from '../types';
+/**
+ * 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
+ */
+export 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.
+ */
+export type EntryMetadata = {
+    context?: string;
+    id?: string;
+    hash?: string;
+    dataFormat?: DataFormat;
+    sourceLocale?: string;
+    actionType?: ActionType;
+    timeout?: number;
+};
+/**
+ * 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 requestMetadata - The metadata for the request.
+ */
+export type Entry = {
+    source: Content;
+    targetLocale?: string;
+    requestMetadata?: EntryMetadata;
+};

package/dist/types-dir/fetchTranslations.d.ts

@@ -0,0 +1,11 @@
+export type FetchTranslationsOptions = {
+    timeout?: number;
+};
+export type RetrievedTranslation = {
+    locale: string;
+    translation: any;
+};
+export type RetrievedTranslations = RetrievedTranslation[];
+export type FetchTranslationsResult = {
+    translations: RetrievedTranslations;
+};

package/dist/types-dir/file.d.ts

@@ -0,0 +1,23 @@
+import { Entry } from './entry';
+export type FileFormat = 'JSON' | 'YAML' | 'MDX' | 'MD' | 'TS' | 'JS';
+export type FileMetadata = {
+    filePath: string;
+    fileFormat: FileFormat;
+    context?: string;
+    sourceLocale?: string;
+    hash?: string;
+};
+export type File = {
+    source: Entry[] | string;
+    fileMetadata: FileMetadata;
+};
+export type CompletedFileTranslationData = {
+    locale: string;
+    metadata: any;
+    fileId: string;
+    fileName: string;
+    versionId: string;
+    id: string;
+    isReady: boolean;
+    downloadUrl: string;
+};

package/dist/types-dir/translate.d.ts

@@ -0,0 +1,34 @@
+import { I18nextMessage, IcuMessage, JsxChildren } from './content';
+/**
+ * TranslationResultReference is used to store the reference for a translation result.
+ */
+export type TranslationResultReference = {
+    id?: string;
+    hash: string;
+};
+/**
+ * TypedResult is a union type that represents the different types of translations that can be returned.
+ */
+export 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.
+ */
+export type TranslationError = {
+    error: string;
+    code: number;
+    reference?: TranslationResultReference;
+};
+/**
+ * RequestSuccess is a type that represents a successful translation request.
+ */
+export type RequestSuccess = TypedResult & {
+    locale: string;
+    reference: TranslationResultReference;
+};
+export type TranslationResult = RequestSuccess | TranslationError;

package/dist/types-dir/translateMany.d.ts

@@ -0,0 +1,5 @@
+import { TranslationResult } from './translate';
+/**
+ * BatchTranslationResult is the result of a batch translation request.
+ */
+export type TranslateManyResult = Array<TranslationResult>;

package/dist/types-dir/translationStatus.d.ts

@@ -0,0 +1,9 @@
+export type TranslationStatusResult = {
+    count: number;
+    availableLocales: string[];
+    locales: string[];
+    localesWaitingForApproval: any[];
+};
+export type CheckTranslationStatusOptions = {
+    timeout?: number;
+};

package/dist/types-dir/variables.d.ts

@@ -0,0 +1,9 @@
+export type VariableType = 'v' | 'n' | 'd' | 'c';
+/**
+ * Variables are used to store the variable name and type.
+ */
+export type Variable = {
+    k: string;
+    i?: number;
+    v?: VariableType;
+};

package/dist/types.cjs.min.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.cjs.min.cjs","sources":["../src/types.ts"],"sourcesContent":["import { LocaleProperties } from './locales/getLocaleProperties';\n\nexport { LocaleProperties };\n\nexport type Content = string | Array<string | Variable>;\n\n/**\n * Map of data-_gt properties to their corresponding React props\n */\nexport const HTML_CONTENT_PROPS = {\n  pl: 'placeholder',\n  ti: 'title',\n  alt: 'alt',\n  arl: 'aria-label',\n  arb: 'aria-labelledby',\n  ard: 'aria-describedby',\n} as const;\n\nexport type HtmlContentPropKeysRecord = Partial<\n  Record<keyof typeof HTML_CONTENT_PROPS, string>\n>;\nexport type HtmlContentPropValuesRecord = Partial<\n  Record<(typeof HTML_CONTENT_PROPS)[keyof typeof HTML_CONTENT_PROPS], string>\n>;\n\n/**\n * Transformations are made from a prefix and a suffix.\n */\nexport type Transformation =\n  | 'translate-client'\n  | 'translate-server'\n  | 'variable-variable'\n  | 'variable-currency'\n  | 'variable-datetime'\n  | 'variable-number'\n  | 'plural'\n  | 'branch';\nexport type TransformationPrefix =\n  | 'translate'\n  | 'variable'\n  | 'plural'\n  | 'branch'\n  | 'fragment';\nexport type VariableTransformationSuffix =\n  | 'variable'\n  | 'number'\n  | 'datetime'\n  | 'currency';\n\n/**\n * GTProp is an internal property used to contain data for translating and rendering elements.\n * note, transformations are only read on the server side if they are 'plural' or 'branch'\n */\nexport type GTProp = {\n  b?: Record<string, JsxChildren>; // Branches\n  t?: 'p' | 'b'; // Branch Transformation\n} & HtmlContentPropKeysRecord;\n\nexport type JsxElement = {\n  t?: string; // tag name\n  i?: number; // id\n  d?: GTProp; // GT data\n  c?: JsxChildren; // children\n};\n\nexport type JsxChild = string | JsxElement | Variable;\nexport type JsxChildren = JsxChild | JsxChild[];\n\nexport type Metadata = {\n  context?: string;\n  id?: string;\n  sourceLocale?: string;\n  actionType?: 'standard' | 'fast' | string;\n  [key: string]: any;\n};\n\nexport type DataFormat = 'JSX' | 'ICU' | 'I18NEXT';\n\nexport type FormatVariables = Record<\n  string,\n  string | number | boolean | null | undefined | Date\n>;\n\nexport type Update =\n  | {\n      type: 'content';\n      data: {\n        source: Content;\n        metadata: Metadata;\n      };\n    }\n  | {\n      type: 'jsx';\n      data: {\n        source: JsxChildren;\n        metadata: Metadata;\n      };\n    };\n\nexport type Request =\n  | {\n      type: 'content';\n      data: {\n        source: Content;\n        targetLocale: string;\n        metadata: Metadata;\n      };\n    }\n  | {\n      type: 'jsx';\n      data: {\n        source: JsxChildren;\n        targetLocale: string;\n        metadata: Metadata;\n      };\n    };\n\nexport type ContentTranslationResult = {\n  translation: Content;\n  locale: string;\n  reference?: {\n    id: string;\n    key: string;\n  };\n};\n\nexport type IcuTranslationResult = {\n  translation: string;\n  locale: string;\n  reference?: {\n    id: string;\n    key: string;\n  };\n};\n\nexport type JsxTranslationResult = {\n  translation: JsxChildren;\n  locale: string;\n  reference?: {\n    id: string;\n    key: string;\n  };\n};\n\nexport type TranslationError = {\n  error: string;\n  code: number;\n  reference?: {\n    id: string;\n    key: string;\n  };\n};\n\nexport type { CustomMapping } from './locales/customLocaleMapping';\n\n// ----- VARIABLES ----- //\n\nexport type VariableType =\n  | 'v' // Variable\n  | 'n' // Number\n  | 'd' // Date\n  | 'c'; // Currency\n\n/**\n * Variables are used to store the variable name and type.\n */\nexport type Variable = {\n  k: string;\n  i?: number;\n  v?: VariableType;\n};\n"],"names":["pl","ti","alt","arl","arb","ard"],"mappings":"wCASkC,CAChCA,GAAI,cACJC,GAAI,QACJC,IAAK,MACLC,IAAK,aACLC,IAAK,kBACLC,IAAK"}
+{"version":3,"file":"types.cjs.min.cjs","sources":["../src/types-dir/content.ts"],"sourcesContent":["import { Variable } from './variables';\n\n/**\n * Map of data-_gt properties to their corresponding React props\n */\nexport const HTML_CONTENT_PROPS = {\n  pl: 'placeholder',\n  ti: 'title',\n  alt: 'alt',\n  arl: 'aria-label',\n  arb: 'aria-labelledby',\n  ard: 'aria-describedby',\n} as const;\n\nexport type HtmlContentPropKeysRecord = Partial<\n  Record<keyof typeof HTML_CONTENT_PROPS, string>\n>;\nexport type HtmlContentPropValuesRecord = Partial<\n  Record<(typeof HTML_CONTENT_PROPS)[keyof typeof HTML_CONTENT_PROPS], string>\n>;\n\n/**\n * GTProp is an internal property used to contain data for translating and rendering elements.\n * note, transformations are only read on the server side if they are 'plural' or 'branch'\n */\nexport type GTProp = {\n  b?: Record<string, JsxChildren>; // Branches\n  t?: 'p' | 'b'; // Branch Transformation\n} & HtmlContentPropKeysRecord;\n\nexport type JsxElement = {\n  t?: string; // tag name\n  i?: number; // id\n  d?: GTProp; // GT data\n  c?: JsxChildren; // children\n};\n\nexport type JsxChild = string | JsxElement | Variable;\n\n/**\n * The format of the content\n */\nexport type DataFormat = 'JSX' | 'ICU' | 'I18NEXT';\n\n/**\n * A content type representing JSX, ICU, and I18next messages\n */\nexport type Content = JsxChildren | IcuMessage | I18nextMessage;\n\n/**\n * A content type representing JSX elements\n */\nexport type JsxChildren = JsxChild | JsxChild[];\n\n/**\n * A content type representing ICU messages\n */\nexport type IcuMessage = string;\n\n/**\n * A content type representing I18next messages\n */\nexport type I18nextMessage = string;\n"],"names":["pl","ti","alt","arl","arb","ard"],"mappings":"wCAKkC,CAChCA,GAAI,cACJC,GAAI,QACJC,IAAK,MACLC,IAAK,aACLC,IAAK,kBACLC,IAAK"}