feat: accept any language code string in the language parameters

The language parameters of translateText(), translateDocument(),
uploadDocument(), createGlossary() and createGlossaryWithCsv() now use the
new SourceLanguageCodeInput, TargetLanguageCodeInput and LanguageCodeInput
types, which accept any string while keeping autocompletion for the listed
codes. Result types are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hive-bot

CHANGELOG.md

@@ -67,6 +67,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Target languages `en` and `pt` are no longer rejected client-side as deprecated;
   the DeepL API translates them as `en-US` and `pt-PT`. `TargetLanguageCode` now
   includes `en` and `pt`.
+- The language parameters of `translateText()`, `translateDocument()`,
+  `uploadDocument()`, `createGlossary()` and `createGlossaryWithCsv()` accept
+  any language code string, so languages the API adds can be used without a new
+  release of this package. They use the new `SourceLanguageCodeInput`,
+  `TargetLanguageCodeInput` and `LanguageCodeInput` types, which keep editor
+  autocompletion for the listed codes. Result types are unchanged.
 
 ### Deprecated
 - `TranslateTextOptions.__path` is deprecated. It is for internal use only

README.md

@@ -116,6 +116,12 @@ languages without a variant use a default variant, for example `'en'` translates
 to `'en-US'` and `'pt'` to `'pt-PT'`. The source language also accepts `null`, to
 enable auto-detection of the source language.
 
+The language parameters accept any language code returned by
+`getSourceLanguages()` and `getTargetLanguages()`, not only the members of the
+`SourceLanguageCode` and `TargetLanguageCode` types. In TypeScript, a code held
+in a `string` variable can be passed without a cast; the codes are sent to the
+API unchanged apart from the case standardization.
+
 The last argument to `translateText()` is optional, and specifies extra
 translation options, see [Text translation options](#text-translation-options)
 below.

src/translator.ts

@@ -33,9 +33,9 @@ import {
     GlossaryInfo,
     GlossaryLanguagePair,
     Language,
-    LanguageCode,
-    SourceLanguageCode,
-    TargetLanguageCode,
+    LanguageCodeInput,
+    SourceLanguageCodeInput,
+    TargetLanguageCodeInput,
     TranslateTextOptions,
     TranslatorOptions,
     TextResult,
@@ -238,8 +238,8 @@ export class Translator {
      */
     async translateText<T extends string | string[]>(
         texts: T,
-        sourceLang: SourceLanguageCode | null,
-        targetLang: TargetLanguageCode,
+        sourceLang: SourceLanguageCodeInput | null,
+        targetLang: TargetLanguageCodeInput,
         options?: TranslateTextOptions,
     ): Promise<T extends string ? TextResult : TextResult[]> {
         const data = buildURLSearchParams(
@@ -289,8 +289,8 @@ export class Translator {
     async translateDocument(
         inputFile: string | Buffer | fs.ReadStream | fs.promises.FileHandle,
         outputFile: string | fs.WriteStream | fs.promises.FileHandle,
-        sourceLang: SourceLanguageCode | null,
-        targetLang: TargetLanguageCode,
+        sourceLang: SourceLanguageCodeInput | null,
+        targetLang: TargetLanguageCodeInput,
         options?: DocumentTranslateOptions,
     ): Promise<DocumentStatus> {
         // Helper function to open output file if provided as filepath and remove it on error
@@ -369,8 +369,8 @@ export class Translator {
      */
     async uploadDocument(
         inputFile: string | Buffer | fs.ReadStream | fs.promises.FileHandle,
-        sourceLang: SourceLanguageCode | null,
-        targetLang: TargetLanguageCode,
+        sourceLang: SourceLanguageCodeInput | null,
+        targetLang: TargetLanguageCodeInput,
         options?: DocumentTranslateOptions,
     ): Promise<DocumentHandle> {
         if (isString(inputFile)) {
@@ -507,8 +507,8 @@ export class Translator {
      */
     async createGlossary(
         name: string,
-        sourceLang: LanguageCode,
-        targetLang: LanguageCode,
+        sourceLang: LanguageCodeInput,
+        targetLang: LanguageCodeInput,
         entries: GlossaryEntries,
     ): Promise<GlossaryInfo> {
         if (Object.keys(entries.entries()).length === 0) {
@@ -530,8 +530,8 @@ export class Translator {
      */
     async createGlossaryWithCsv(
         name: string,
-        sourceLang: LanguageCode,
-        targetLang: LanguageCode,
+        sourceLang: LanguageCodeInput,
+        targetLang: LanguageCodeInput,
         csvFile: string | Buffer | fs.ReadStream | fs.promises.FileHandle,
     ): Promise<GlossaryInfo> {
         let csvContent;
@@ -613,8 +613,8 @@ export class Translator {
      */
     private async internalUploadDocument(
         fileBuffer: Buffer,
-        sourceLang: SourceLanguageCode | null,
-        targetLang: TargetLanguageCode,
+        sourceLang: SourceLanguageCodeInput | null,
+        targetLang: TargetLanguageCodeInput,
         filename: string,
         options?: DocumentTranslateOptions,
     ): Promise<DocumentHandle> {
@@ -678,8 +678,8 @@ export class Translator {
      */
     private async internalCreateGlossary(
         name: string,
-        sourceLang: LanguageCode,
-        targetLang: LanguageCode,
+        sourceLang: LanguageCodeInput,
+        targetLang: LanguageCodeInput,
         entriesFormat: string,
         entries: string,
     ): Promise<GlossaryInfo> {

src/types.ts

@@ -456,6 +456,24 @@ export type TargetLanguageCode =
  */
 export type LanguageCode = SourceLanguageCode | TargetLanguageCode;
 
+/**
+ * Accepted for source-language parameters: any {@link SourceLanguageCode}, or any other language
+ * code string (e.g. one returned by getSourceLanguages() that this package does not list yet).
+ */
+export type SourceLanguageCodeInput = SourceLanguageCode | (string & Record<never, never>);
+
+/**
+ * Accepted for target-language parameters: any {@link TargetLanguageCode}, or any other language
+ * code string (e.g. one returned by getTargetLanguages() that this package does not list yet).
+ */
+export type TargetLanguageCodeInput = TargetLanguageCode | (string & Record<never, never>);
+
+/**
+ * Accepted for language parameters that take source or target languages: any
+ * {@link LanguageCode}, or any other language code string.
+ */
+export type LanguageCodeInput = LanguageCode | (string & Record<never, never>);
+
 /**
  * Language codes that do not include a regional variant, for example 'en' is included, but 'en-US'
  * is not.

src/utils.ts

@@ -9,6 +9,7 @@ import {
     GlossaryInfo,
     GlossaryId,
     LanguageCode,
+    LanguageCodeInput,
     NonRegionalLanguageCode,
     RequestParameters,
     SentenceSplittingMode,
@@ -160,8 +161,8 @@ function joinTagList(tagList: TagList): string {
  * @private
  */
 export function buildURLSearchParams(
-    sourceLang: LanguageCode | null,
-    targetLang: LanguageCode,
+    sourceLang: LanguageCodeInput | null,
+    targetLang: LanguageCodeInput,
     formality: Formality | undefined,
     glossary: GlossaryId | GlossaryInfo | MultilingualGlossaryInfo | undefined,
     extraRequestParameters: RequestParameters | undefined,

tests/offline/translateText.test.ts

@@ -27,6 +27,13 @@ describe('Translator.translateText', () => {
         await makeTranslator().translateText('abc', null, 'de');
     });
 
+    it('accepts a target language held in a string variable', async () => {
+        expectTranslateBody({ ...baseBody, target_lang: 'de-AT' });
+        const targets: string[] = ['de-AT'];
+
+        await makeTranslator().translateText('abc', null, targets[0]);
+    });
+
     it('parses the detected language, billed characters and model type', async () => {
         expectTranslateBody(baseBody, {
             translations: [