Skip to content

upgrading_to_multilingual_glossaries.md

Latest commit

 

History

History
206 lines (176 loc) · 13.2 KB

upgrading_to_multilingual_glossaries.md

File metadata and controls

206 lines (176 loc) · 13.2 KB

Migration Documentation for Newest Glossary Functionality

1. Overview of Changes

The newest version of the Glossary APIs is the /v3 endpoints, which introduce enhanced functionality:

  • Support for Multilingual Glossaries: The v3 endpoints allow for the creation of glossaries with multiple language pairs, enhancing flexibility and usability.
  • Editing Capabilities: Users can now edit existing glossaries.

To support these new v3 APIs, we have created new methods to interact with these new multilingual glossaries. Users are encouraged to transition to the new to take full advantage of these new features. The v2 methods for monolingual glossaries (e.g., createGlossary(), getGlossary(), etc.) remain available, however users are encouraged to update to use the new functions.

2. Endpoint Changes

Monolingual glossary methods Multilingual glossary methods Changes Summary
createGlossary() createMultilingualGlossary() Accepts an array of MultilingualGlossaryDictionaryEntries for multi-lingual support and now returns a MultilingualGlossaryInfo object.
createGlossaryWithCsv() createMultilingualGlossaryWithCsv() Similar functionality, but now returns a MultilingualGlossaryInfo object
getGlossary() getMultilingualGlossary() Similar functionality, but now returns MultilingualGlossaryInfo. Also can accept a MultilingualGlossaryInfo object as the glossary parameter instead of a GlossaryInfo object.
listGlossaries() listMultilingualGlossaries() Similar functionality, but now returns a list of MultilingualGlossaryInfo objects.
getGlossaryEntries() getMultilingualGlossaryDictionaryEntries() Requires specifying source and target languages. Also returns a MultilingualGlossaryDictionaryEntries object as the response.
deleteGlossary() deleteMultilingualGlossary() Similar functionality, but now can accept a MultilingualGlossaryInfo object instead of a GlossaryInfo object when specifying the glossary.

3. Model Changes

V2 glossaries are monolingual and the previous glossary objects could only have entries for one language pair (sourceLang and targetLang). Now we introduce the concept of "glossary dictionaries", where a glossary dictionary specifies its own sourceLangCode, targetLangCode, and has its own entries.

  • Glossary Information:

    • v2: GlossaryInfo supports only mono-lingual glossaries, containing fields such as sourceLang, targetLang, and entryCount.
    • v3: MultilingualGlossaryInfo supports multi-lingual glossaries and includes a list of MultilingualGlossaryDictionaryInfo, which provides details about each glossary dictionary, each with its own sourceLangCode, targetLangCode, and entryCount.

  • Glossary Entries:

    • v3: Introduces MultilingualGlossaryDictionaryEntries, which encapsulates a glossary dictionary with source and target languages along with its entries.

4. Code Examples

Create a glossary

// monolingual glossary example
const glossaryInfo = await deeplClient.createGlossary('My Glossary', 'en', 'de', new deepl.GlossaryEntries({ entries: { Hello: 'Hallo' } }));

// multilingual glossary example
const glossaryDicts = [{sourceLangCode: 'en', targetLangCode: 'de', entries: new deepl.GlossaryEntries({ entries: { Hello: 'Hallo' } })}];
const glossaryInfo = await deeplClient.createMultilingualGlossary('My Glossary', glossaryDicts);

Get a glossary

// monolingual glossary example
const createdGlossary = await deeplClient.createGlossary('My Glossary', 'en', 'de', new deepl.GlossaryEntries({ entries: { Hello: 'Hallo' } }));
const glossaryInfo = await deeplClient.getGlossary(createdGlossary); // GlossaryInfo object

// multilingual glossary example
const glossaryDicts = [{sourceLangCode: 'en', targetLangCode: 'de', entries: new deepl.GlossaryEntries({ entries: { Hello: 'Hallo' } })}];
const createdGlossary = await deeplClient.createMultilingualGlossary('My Glossary', glossaryDicts);
const glossaryInfo = await deeplClient.getMultilingualGlossary(createdGlossary); // MultilingualGlossaryInfo object

Get glossary entries

// monolingual glossary example
const createdGlossary = await deeplClient.createGlossary('My Glossary', 'en', 'de', new deepl.GlossaryEntries({ entries: { Hello: 'Hallo' } }));
const entries = await deeplClient.getGlossaryEntries(createdGlossary);
console.log(entries.toTsv()); // 'hello\thallo'

// multilingual glossary example
const glossaryDicts = [{sourceLangCode: 'en', targetLangCode: 'de', entries: new deepl.GlossaryEntries({ entries: { Hello: 'Hallo' } })}];
const createdGlossary = await deeplClient.createMultilingualGlossary('My Glossary', glossaryDicts);
const entriesObj = await deeplClient.getMultilingualGlossaryDictionaryEntries(createdGlossary, 'en', 'de');
console.log(entriesObj.entries.toTsv()); // 'hello\thallo'

List and delete glossaries

// monolingual glossary example
const glossaries = await deeplClient.listGlossaries();
for (const glossary of glossaries) {
  if (glossary.name === "Old glossary") {
    await deeplClient.deleteGlossary(glossary);
  }
}

// multilingual glossary example
const glossaries = await deeplClient.listMultilingualGlossaries();
for (const glossary of glossaries) {
  if (glossary.name === "Old glossary") {
    await deeplClient.deleteMultilingualGlossary(glossary);
  }
}

5. New Multilingual Glossary Methods

In addition to introducing multilingual glossaries, we introduce several new methods that enhance the functionality for managing glossaries. Below are the details for each new method:

Update Multilingual Glossary Dictionary

  • Method: async updateMultilingualGlossaryDictionary(glossary: GlossaryId | MultilingualGlossaryInfo, glossaryDict: MultilingualGlossaryDictionaryEntries): Promise<MultilingualGlossaryInfo>
  • Description: Use this method to update or create a glossary dictionary's entries
  • Parameters:
    • glossary: The ID or MultilingualGlossaryInfo of the glossary to update.
    • glossaryDict: The glossary dictionary including its new entries.
  • Returns: MultilingualGlossaryInfo containing information about the updated glossary.
  • Note: This method will either update the glossary's entries if they exist for the given glossary dictionary's language pair, or adds any new ones to the dictionary if not. It will also create a new glossary dictionary if one did not exist for the given language pair.
  • Example: 
      const glossaryDicts = [{sourceLangCode: 'en', targetLangCode: 'de', entries: new deepl.GlossaryEntries({ entries: {"artist": "Maler", "hello": "guten tag"} })}];
  const myGlossary = await deeplClient.createMultilingualGlossary('My Glossary', glossaryDicts);
  const newDict = {sourceLangCode: 'en', targetLangCode: 'de', entries: new deepl.GlossaryEntries({ entries: {"hello": "hallo", "prize": "Gewinn"} })};
  const updatedGlossary = await deeplClient.updateMultilingualGlossaryDictionary(myGlossary, newDict);

  const entriesObj = await deeplClient.getMultilingualGlossaryDictionaryEntries(createdGlossary, 'en', 'de');
  console.log(entriesObj.entries.toTsv()); // {'artist': 'Maler', 'hello': 'hallo', 'prize': 'Gewinn'}

Update Multilingual Glossary Dictionary from CSV

  • Method: async updateMultilingualGlossaryDictionaryWithCsv(glossary: GlossaryId | MultilingualGlossaryInfo, sourceLanguageCode: string, targetLanguageCode: string, csvContent: string): Promise<MultilingualGlossaryInfo>
  • Description: This method allows you to update or create a glossary dictionary using entries in CSV format.
  • Parameters:
    • glossary: The ID or MultilingualGlossaryInfo of the glossary to update.
    • sourceLanguageCode: Language of source entries.
    • targetLanguageCode: Language of target entries.
    • csvContent: CSV-formatted string containing glossary entries.
  • Returns: MultilingualGlossaryInfo containing information about the updated glossary.
  • Example: 
      const fs = require('fs').promises;
  const filePath = '/path/to/glossary_file.csv';
  let csvContent = '';
  try {
      csvContent = await fs.readFile(filePath, 'utf-8');
  } catch (error) {
      console.error(`Error reading file at ${filePath}:`, error);
      throw error;
  }
  const csvContent = await readCsvFile(filePath);
  const updatedGlossary = await deeplClient.updateMultilingualGlossaryDictionaryWithCsv('4c81ffb4-2e...', 'en', 'de', csvContent);

Update Multilingual Glossary Name

  • Method: async updateMultilingualGlossaryName(glossary: GlossaryId | MultilingualGlossaryInfo, name: string): Promise<MultilingualGlossaryInfo>
  • Description: This method allows you to update the name of an existing glossary.
  • Parameters:
    • glossary: The ID or MultilingualGlossaryInfo of the glossary to update.
    • name: The new name for the glossary.
  • Returns: MultilingualGlossaryInfo containing information about the updated glossary.
  • Example: 
    const updatedGlossary = deeplGlient.updateMultilingualGlossaryName('4c81ffb4-2e...', 'New Glossary Name')

Replace a Multilingual Glossary Dictionary

  • Method: async replaceMultilingualGlossaryDictionary(glossary: GlossaryId | MultilingualGlossaryInfo, glossaryDict: MultilingualGlossaryDictionaryEntries): Promise<MultilingualGlossaryDictionaryInfo>
  • Description: This method replaces the existing glossary dictionary with a new set of entries.
  • Parameters:
    • glossary: The ID or MultilingualGlossaryInfo of the glossary to update.
    • glossaryDict: The glossary dictionary that overwrites any existing one.
  • Returns: MultilingualGlossaryInfo containing information about the updated glossary.
  • Note: Ensure that the new dictionary entries are complete and valid, as this method will completely overwrite the existing entries. It will also create a new glossary dictionary if one did not exist for the given language pair.
  • Example: 
    const newGlossaryDict = {sourceLangCode: 'en', targetLangCode: 'de', entries: new deepl.GlossaryEntries({ entries: {"goodbye": "auf Wiedersehen"} })};
const replacedGlossary = await deeplClient.replaceMultilingualGlossaryDictionary("4c81ffb4-2e...", newGlossaryDict)

Replace Multilingual Glossary Dictionary from CSV

  • Method: async replaceMultilingualGlossaryDictionaryWithCsv(glossary: GlossaryId | MultilingualGlossaryInfo, sourceLanguageCode: string, targetLanguageCode: string, csvContent: string): Promise<MultilingualGlossaryDictionaryInfo>
  • Description: This method allows you to replace or create a glossary dictionary using entries in CSV format.
  • Parameters:
    • glossary: The ID or MultilingualGlossaryInfo of the glossary to update.
    • sourceLanguageCode: Language of source entries.
    • targetLanguageCode: Language of target entries.
    • csvContent: CSV-formatted string containing glossary entries.
  • Returns: MultilingualGlossaryInfo containing information about the updated glossary.
  • Example: 
      const fs = require('fs').promises;
  const filePath = '/path/to/glossary_file.csv';
  let csvContent = '';
  try {
      csvContent = await fs.readFile(filePath, 'utf-8');
  } catch (error) {
      console.error(`Error reading file at ${filePath}:`, error);
      throw error;
  }
  const csvContent = await readCsvFile(filePath);
  const myCsvGlossary = await deeplClient.replaceMultilingualGlossaryDictionaryWithCsv('4c81ffb4-2e...', 'en', 'de', csvContent);

Delete a Multilingual Glossary Dictionary

  • Method: async deleteMultilingualGlossaryDictionary(glossary: GlossaryId | MultilingualGlossaryInfo, sourceLanguageCode: string, targetLanguageCode: string): Promise<void>

  • Description: This method deletes a specified glossary dictionary from a given glossary.

  • Parameters:

    • glossary: The ID or MultilingualGlossaryInfo of the glossary containing the dictionary to delete.
    • sourceLanguageCode: The source language of the dictionary to be deleted.
    • targetLanguageCode: The target language of the dictionary to be deleted.

  • Returns: None

  • Migration Note: Ensure that your application logic correctly identifies the dictionary to delete. Both sourceLanguageCode and targetLanguageCode must be provided to specify the dictionary.

  • Example:

    const glossaryDicts = [{sourceLangCode: 'en', targetLangCode: 'de', entries: new deepl.GlossaryEntries({ entries: {'hello': 'hallo'}})}, {sourceLangCode: 'de', targetLangCode: 'en', entries: new deepl.GlossaryEntries({ entries: {'hallo': 'hello'}})}];
const createdGlossary = await deeplClient.createMultilingualGlossary('My Glossary', glossaryDicts);

// Delete via specifying the language pair
await deeplClient.deleteMultilingualGlossaryDictionary(createdGlossary, 'de', 'en');