feat: allow a glossary without a source language in text translation

translateText() no longer rejects the glossary and glossaryIds options when
sourceLang is null; the API detects the source language and uses the
glossary's dictionary for the detected language pair. Document translation
with a glossary still requires sourceLang and keeps the client-side check.

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

Author: hive-bot

CHANGELOG.md

@@ -172,6 +172,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   as a glossary ID.
 
 ### Changed
+- `translateText()` accepts the `glossary` and `glossaryIds` options without a
+  source language; the API detects the source language and uses the glossary's
+  dictionary for the detected language pair. Document translation with a
+  glossary still requires a source language.
 - `Formality`, `SentenceSplittingMode`, `TagHandlingMode`, `TagHandlingVersion`
   and `ModelType` accept any string in addition to their listed values, so values
   the API adds later can be passed without a type cast.

README.md

@@ -193,8 +193,8 @@ console.log(await deeplClient.translateText('How are you?', null, 'de', { formal
     `getMultilingualGlossary()`/`getGlossary()`.
 -   `glossaryIds`: specifies up to 5 glossaries to use with translation, as an array of
     glossary ID strings, `MultilingualGlossaryInfo`, or `GlossaryInfo` objects. Glossaries are
-    applied in the order given, with the first matching term taking precedence. Requires
-    `sourceLang` to be set, and cannot be combined with the singular `glossary` option.
+    applied in the order given, with the first matching term taking precedence. Cannot be
+    combined with the singular `glossary` option.
 -   `styleRule`: specifies a style rule to use with translation, either as a string
     containing the style rule ID, or a `StyleRuleInfo` as returned by `getAllStyleRules()`.
 -   `styleProfile`: specifies a style profile to use with translation, either as a
@@ -326,7 +326,9 @@ statuses this library does not know.
 
 -   `formality`: same as in [Text translation options](#text-translation-options).
 -   `glossary`: same as in [Text translation options](#text-translation-options).
+    Requires `sourceLang` to be set.
 -   `glossaryIds`: same as in [Text translation options](#text-translation-options).
+    Requires `sourceLang` to be set.
 -   `styleRule`: same as in [Text translation options](#text-translation-options).
 -   `styleProfile`: same as in [Text translation options](#text-translation-options).
     A style profile that does not exist fails the translation with a
@@ -485,7 +487,11 @@ for (const glossaryDict of glossary.dictionaries) {
 
 To use a glossary when translating text and documents, include the ID
 (or `MultilingualGlossaryInfo` object returned by `listMultilingualGlossaries()` or `createMultilingualGlossary()`) in
-the function call. The source and target languages must match the glossary.
+the function call. The glossary needs a dictionary for the source and target
+languages. For text translation, `sourceLang` may be `null`: DeepL detects the
+source language and uses the dictionary for the detected language pair, and the
+request fails if the glossary has none. Document translation with a glossary
+requires `sourceLang`.
 
 ```javascript
 const resultWithGlossary = await deeplClient.translateText(

src/translator.ts

@@ -717,6 +717,14 @@ export class Translator {
             options?.glossary,
             options?.glossaryIds,
         );
+        // Text translation detects the source language for a glossary; document translation
+        // with a glossary requires sourceLang.
+        const hasGlossary =
+            options?.glossary !== undefined ||
+            (options?.glossaryIds !== undefined && options.glossaryIds.length > 0);
+        if (hasGlossary && sourceLang === null) {
+            throw new DeepLError('sourceLang is required if using a glossary');
+        }
         appendStyleAndTranslationMemoryOptions(data, options ?? {});
         if (options?.outputFormat !== undefined) {
             data.append('output_format', options.outputFormat);

src/types.ts

@@ -204,8 +204,9 @@ export interface TranslateTextOptions extends BaseRequestOptions {
      * precedence. Accepts glossary ID strings, GlossaryInfo, or
      * MultilingualGlossaryInfo objects (the `.glossaryId` is extracted).
      *
-     * Requires `sourceLang` to be set. Cannot be combined with the singular
-     * `glossary` option.
+     * Without `sourceLang`, DeepL detects the source language and uses the
+     * glossary's dictionary for the detected language pair. Cannot be combined
+     * with the singular `glossary` option.
      */
     glossaryIds?: Array<GlossaryId | GlossaryInfo | MultilingualGlossaryInfo>;
 

src/utils.ts

@@ -191,8 +191,8 @@ export function buildURLSearchParams(
         sourceLang = standardizeLanguageCode(sourceLang);
     }
 
-    // Treat an empty glossaryIds array as "no glossaries" so it doesn't enforce
-    // the sourceLang requirement or append an empty glossary_ids parameter.
+    // Treat an empty glossaryIds array as "no glossaries" so it doesn't append an
+    // empty glossary_ids parameter.
     const hasGlossaryIds = glossaryIds !== undefined && glossaryIds.length > 0;
 
     if (glossary !== undefined && hasGlossaryIds) {
@@ -201,10 +201,6 @@ export function buildURLSearchParams(
         );
     }
 
-    if ((glossary !== undefined || hasGlossaryIds) && sourceLang === null) {
-        throw new DeepLError('sourceLang is required if using a glossary');
-    }
-
     if (glossaryIds !== undefined && glossaryIds.length > 5) {
         throw new DeepLError('glossaryIds option supports at most 5 glossaries.');
     }

tests/offline/translateDocument.test.ts

@@ -67,6 +67,19 @@ describe('Translator.uploadDocument', () => {
         expect(result).toEqual(handle);
     });
 
+    it.each([
+        ['glossary', { glossary: 'g-1' }],
+        ['glossaryIds', { glossaryIds: ['g-1'] }],
+    ])('throws DeepLError when %s is set without a source language', async (_, options) => {
+        // No request is declared: nock rejects any request with a different error.
+        await expect(
+            makeTranslator().uploadDocument(Buffer.from('x'), null, 'de', {
+                filename: 'example.txt',
+                ...options,
+            }),
+        ).rejects.toThrow(new deepl.DeepLError('sourceLang is required if using a glossary'));
+    });
+
     it('sends extraBodyParameters as multipart parts', async () => {
         const upload = expectUpload();
 

tests/offline/translateText.test.ts

@@ -383,12 +383,13 @@ describe('Translator.translateText', () => {
     });
 
     it.each([
-        ['glossary', { glossary: 'g-1' }],
-        ['glossaryIds', { glossaryIds: ['g-1'] }],
-    ])('throws DeepLError when %s is set without a source language', async (_, options) => {
-        await expect(makeTranslator().translateText('abc', null, 'de', options)).rejects.toThrow(
-            /sourceLang is required/,
-        );
+        ['glossary', { glossary: 'g-1' }, { glossary_id: 'g-1' }],
+        ['glossaryIds', { glossaryIds: ['g-1'] }, { glossary_ids: 'g-1' }],
+    ])('sends %s without a source language', async (_, options, glossaryParam) => {
+        // nock matches the exact body, so a source_lang field would fail the match.
+        expectTranslateBody({ ...baseBody, ...glossaryParam });
+
+        await makeTranslator().translateText('abc', null, 'de', options);
     });
 
     it('throws DeepLError when translationMemoryThreshold is set without a translation memory', async () => {