npm Package
When you install the widget via npm, types are included automatically through the types field in package.json. No extra setup is needed:
npm install translation-widget
import TranslationWidget from "translation-widget";
TranslationWidget("YOUR_PUBLIC_KEY", {
pageLanguage: "en",
position: "top-right",
});
CDN / Script Tag Method
When you load the widget via a <script> tag, TypeScript has no knowledge of window.TranslationWidget. You need to declare it manually.
Add the following global declaration to a types.d.ts or global.d.ts file in your project root:
declare global {
interface Window {
TranslationWidget: (
publicKey: string,
config?: {
pageLanguage?: string;
position?: "top-right" | "top-left" | "bottom-left" | "bottom-right";
autoDetectLanguage?: boolean;
adjustFontSize?: boolean;
theme?: {
baseColor?: string;
textColor?: string;
};
showUI?: boolean;
}
) => void;
}
}
Declaring the Programmatic API globals
The widget also exposes window.translate, window.resetTranslation, and window.clearCache. Add these declarations alongside the one above:
declare global {
interface Window {
translate: (
langCode: string,
onComplete?: (result: TranslationResult) => void,
onError?: (error: Error) => void
) => Promise<TranslationResult>;
resetTranslation: (
defaultLang: string,
onComplete?: (result: Pick<TranslationResult, "success" | "targetLanguage">) => void,
onError?: (error: Error) => void
) => void;
clearCache: (
lang_code: string[],
onComplete?: () => void,
onError?: (error: Error) => void
) => void;
}
}
Place all global declarations in a single types.d.ts or global.d.ts file
at the root of your project so TypeScript picks them up automatically across
your entire codebase.
Type Reference
TranslationConfig
The full configuration interface accepted by the widget:
export interface TranslationConfig {
pageLanguage?: string;
position?: "top-right" | "top-left" | "bottom-left" | "bottom-right";
autoDetectLanguage?: boolean;
adjustFontSize?: boolean;
theme?: {
baseColor?: string;
textColor?: string;
};
showUI?: boolean;
}
TranslationResult
The result object returned by window.translate and passed to onComplete callbacks:
export interface TranslationResult {
success: boolean;
targetLanguage: string;
translatedNodes: number;
error?: string;
duration?: number;
}