summaryrefslogtreecommitdiffstats
path: root/toolkit/components/translations/translations.d.ts
diff options
context:
space:
mode:
Diffstat (limited to 'toolkit/components/translations/translations.d.ts')
-rw-r--r--toolkit/components/translations/translations.d.ts302
1 files changed, 302 insertions, 0 deletions
diff --git a/toolkit/components/translations/translations.d.ts b/toolkit/components/translations/translations.d.ts
new file mode 100644
index 0000000000..3d6e0f5fd4
--- /dev/null
+++ b/toolkit/components/translations/translations.d.ts
@@ -0,0 +1,302 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+/**
+ * This file contains the shared types for the translations component. The intended use
+ * is for defining types to be used in JSDoc. They are used in a form that the TypeScript
+ * language server can read them, and provide code hints.
+ */
+
+/**
+ * For Remote Settings, the JSON details about the attachment.
+ */
+export interface Attachment {
+ // e.g. "2f7c0f7bbc...ca79f0850c4de",
+ hash: string;
+ // e.g. 5047568,
+ size: string;
+ // e.g. "lex.50.50.deen.s2t.bin",
+ filename: string;
+ // e.g. "main-workspace/translations-models/316ebb3a-0682-42cc-8e73-a3ba4bbb280f.bin",
+ location: string;
+ // e.g. "application/octet-stream"
+ mimetype: string;
+}
+
+/**
+ * The JSON that is synced from Remote Settings for the language-id models.
+ */
+export interface LanguageIdModelRecord {
+ // e.g. "0d4db293-a17c-4085-9bd8-e2e146c85000"
+ id: string;
+ // The full model name, e.g. "lid.176.ftz"
+ name: string;
+ // The semver number, used for handling future format changes. e.g. 1.0
+ version: string;
+ // The file attachment for this record
+ attachment: Attachment;
+ // e.g. 1673455932527
+ last_modified: string;
+ // A JEXL expression to determine whether this record should be pulled from Remote Settings
+ // See: https://remote-settings.readthedocs.io/en/latest/target-filters.html#filter-expressions
+ filter_expression: string;
+}
+
+/**
+ * The JSON that is synced from Remote Settings for the translation models.
+ */
+export interface TranslationModelRecord {
+ // e.g. "0d4db293-a17c-4085-9bd8-e2e146c85000"
+ id: string;
+ // The full model name, e.g. "lex.50.50.deen.s2t.bin"
+ name: string;
+ // The BCP 47 language tag, e.g. "de"
+ fromLang: string;
+ // The BCP 47 language tag, e.g. "en"
+ toLang: string;
+ // The semver number, used for handling future format changes. e.g. 1.0
+ version: string;
+ // e.g. "lex"
+ fileType: string;
+ // The file attachment for this record
+ attachment: Attachment;
+ // e.g. 1673023100578
+ schema: number;
+ // e.g. 1673455932527
+ last_modified: string;
+ // A JEXL expression to determine whether this record should be pulled from Remote Settings
+ // See: https://remote-settings.readthedocs.io/en/latest/target-filters.html#filter-expressions
+ filter_expression: string;
+}
+
+/**
+ * The JSON that is synced from Remote Settings for the wasm binaries.
+ */
+export interface WasmRecord {
+ // e.g. "0d4db293-a17c-4085-9bd8-e2e146c85000"
+ id: string;
+ // The name of the project, e.g. "bergamot-translator"
+ name: string;
+ // The human readable identifier for the release. e.g. "v0.4.4"
+ release: string;
+ // The commit hash for the project that generated the wasm.
+ revision: string;
+ // The license of the wasm, as a https://spdx.org/licenses/
+ license: string;
+ // The semver number, used for handling future format changes. e.g. 1.0
+ version: string;
+ // The file attachment for this record
+ attachment: Attachment;
+ // e.g. 1673455932527
+ last_modified: string;
+ // A JEXL expression to determine whether this record should be pulled from Remote Settings
+ // See: https://remote-settings.readthedocs.io/en/latest/target-filters.html#filter-expressions
+ filter_expression: string;
+}
+
+/**
+ * The following are the types that are provided by the Bergamot wasm library.
+ *
+ * See: https://github.com/mozilla/bergamot-translator/tree/main/wasm/bindings
+ */
+export namespace Bergamot {
+ /**
+ * The main module that is returned from bergamot-translator.js.
+ */
+ export interface ModuleExport {
+ BlockingService: typeof BlockingService;
+ AlignedMemoryList: typeof AlignedMemoryList;
+ TranslationModel: typeof TranslationModel;
+ AlignedMemory: typeof AlignedMemory;
+ VectorResponseOptions: typeof VectorResponseOptions;
+ VectorString: typeof VectorString;
+ }
+
+ /**
+ * This class represents a C++ std::vector. The implementations will extend from it.
+ */
+ export class Vector<T> {
+ size(): number;
+ get(index: number): T;
+ push_back(item: T);
+ }
+
+ export class VectorResponse extends Vector<Response> {}
+ export class VectorString extends Vector<string> {}
+ export class VectorResponseOptions extends Vector<ResponseOptions> {}
+ export class AlignedMemoryList extends Vector<AlignedMemory> {}
+
+ /**
+ * A blocking (e.g. non-threaded) translation service, via Bergamot.
+ */
+ export class BlockingService {
+ /**
+ * Translate multiple messages in a single synchronous API call using a single model.
+ */
+ translate(
+ translationModel,
+ vectorSourceText: VectorString,
+ vectorResponseOptions: VectorResponseOptions
+ ): VectorResponse;
+
+ /**
+ * Translate by pivoting between two models
+ *
+ * For example to translate "fr" to "es", pivot using "en":
+ * "fr" to "en"
+ * "en" to "es"
+ *
+ * See https://github.com/mozilla/bergamot-translator/blob/5ae1b1ebb3fa9a3eabed8a64ca6798154bd486eb/src/translator/service.h#L80
+ */
+ translateViaPivoting(
+ first: TranslationModel,
+ second: TranslationModel,
+ vectorSourceText: VectorString,
+ vectorResponseOptions: VectorResponseOptions
+ ): VectorResponse;
+ }
+
+ /**
+ * The actual translation model, which is passed into the `BlockingService` methods.
+ */
+ export class TranslationModel {}
+
+ /**
+ * The models need to be placed in the wasm memory space. This object represents
+ * aligned memory that was allocated on the wasm side of things. The memory contents
+ * can be set via the getByteArrayView method and the Uint8Array.prototype.set method.
+ */
+ export class AlignedMemory {
+ constructor(size: number, alignment: number);
+ size(): number;
+ getByteArrayView(): Uint8Array;
+ }
+
+ /**
+ * The response from the translation. This definition isn't complete, but just
+ * contains a subset of the available methods.
+ *
+ * See https://github.com/mozilla/bergamot-translator/blob/main/src/translator/response.h
+ */
+ export class Response {
+ getOriginalText(): string;
+ getTranslatedText(): string;
+ }
+
+ /**
+ * The options to configure a translation response.
+ *
+ * See https://github.com/mozilla/bergamot-translator/blob/main/src/translator/response_options.h
+ */
+ export class ResponseOptions {
+ // Include the quality estimations.
+ qualityScores: boolean;
+ // Include the alignments.
+ alignment: boolean;
+ // Remove HTML tags from text and insert it back into the output.
+ html: boolean;
+ // Whether to include sentenceMappings or not. Alignments require
+ // sentenceMappings and are available irrespective of this option if
+ // `alignment=true`.
+ sentenceMappings: boolean
+ }
+}
+
+
+/**
+ * The client to interact with RemoteSettings.
+ * See services/settings/RemoteSettingsClient.jsm
+ */
+interface RemoteSettingsClient {
+ on: Function,
+ get: Function,
+ attachments: any,
+}
+
+/**
+ * A single language model file.
+ */
+interface LanguageTranslationModelFile {
+ buffer: ArrayBuffer,
+ record: TranslationModelRecord,
+}
+
+/**
+ * The files necessary to run the translations, these will be sent to the Bergamot
+ * translation engine.
+ */
+interface LanguageTranslationModelFiles {
+ // The machine learning language model.
+ model: LanguageTranslationModelFile,
+ // The lexical shortlist that limits possible output of the decoder and makes
+ // inference faster.
+ lex: LanguageTranslationModelFile,
+ // A model that can generate a translation quality estimation.
+ qualityModel?: LanguageTranslationModelFile,
+
+ // There is either a single vocab file:
+ vocab?: LanguageTranslationModelFile,
+
+ // Or there are two:
+ srcvocab?: LanguageTranslationModelFile,
+ trgvocab?: LanguageTranslationModelFile,
+};
+
+/**
+ * This is the type that is generated when the models are loaded into wasm aligned memory.
+ */
+type LanguageTranslationModelFilesAligned = {
+ [K in keyof LanguageTranslationModelFiles]: AlignedMemory
+};
+
+/**
+ * These are the files that are downloaded from Remote Settings that are necessary
+ * to start the translations engine. These may not be available if running in tests,
+ * and so the engine will be mocked.
+ */
+interface TranslationsEnginePayload {
+ bergamotWasmArrayBuffer: ArrayBuffer,
+ languageModelFiles: LanguageTranslationModelFiles[]
+ isMocked: boolean,
+}
+
+/**
+ * These are the files that are downloaded from Remote Settings that are necessary
+ * to start the language-identification engine. These may not be available if running
+ * in tests.
+ */
+interface LanguageIdEnginePayload {
+ wasmBuffer: ArrayBuffer,
+ modelBuffer: ArrayBuffer,
+ mockedConfidence: null | number,
+ mockedLangTag: null | string,
+}
+
+/**
+ * Nodes that are being translated are given priority according to their visibility.
+ */
+export type NodeVisibility = "in-viewport" | "out-of-viewport" | "hidden";
+
+/**
+ * Used to decide how to translate a page for full page translations.
+ */
+export interface LangTags {
+ isDocLangTagSupported: boolean,
+ docLangTag: string | null,
+ userLangTag: string | null,
+}
+
+export interface LanguagePair { fromLang: string, toLang: string };
+
+/**
+ * A structure that contains all of the information needed to render dropdowns
+ * for translation language selection.
+ */
+export interface SupportedLanguages {
+ languagePairs: LanguagePair[],
+ fromLanguages: Array<{ langTag: string, isBeta: boolean, displayName: string, }>,
+ toLanguages: Array<{ langTag: string, isBeta: boolean, displayName: string }>,
+}
+
+export type TranslationErrors = "engine-load-error";