until.ts

Overview

The until.ts file provides utility functions for handling nested localization or translation objects. Its primary purpose is to:

• Flatten deeply nested objects into a single-depth key-value map with dot-separated keys.

• Generate translation tables that consolidate multiple flattened language objects into a structured array representing translations across multiple languages.

These utilities are particularly useful in internationalization (i18n) workflows where translation strings are often stored in nested JSON objects per language, and a flattened or tabular format is required for easier processing, editing, or exporting (e.g., to CSV or Excel).

Detailed Documentation

Type Definitions

NestedObject

type NestedObject = {
  [key: string]: string | NestedObject;
};

• Represents a nested object where keys are strings.

• Values can be either strings (leaf nodes) or another nested object (allowing infinite nesting).

• Used as the input for flattening functions.

FlattenedObject

type FlattenedObject = {
  [key: string]: string;
};

• Represents a flat key-value object where keys are strings using dot notation to indicate hierarchy.

• Values are always strings.

• Output from the flattening process.

TranslationTableRow

type TranslationTableRow = {
  key: string;
  [language: string]: string;
};

• Represents a single row in the translation table.

• key: the flattened translation key (dot notation).

• Additional properties: language keys (e.g., "English", "Vietnamese") with their corresponding translated string.

Functions

flattenObject

export function flattenObject(
  obj: NestedObject,
  parentKey: string = '',
): FlattenedObject

Description

Recursively flattens a nested object into a single-depth object with dot-separated keys.

Parameters

• obj: NestedObject — The nested input object to flatten.

• parentKey: string (optional) — The prefix key for recursion, defaults to an empty string.

Returns

• FlattenedObject — A flat object where keys represent the nested path joined by dots.

Implementation Details

• Iterates over each key-value pair in the input object.

• If the value is another nested object, recursively calls flattenObject with the updated key prefix.

• Otherwise, assigns the string value to the appropriate dot-notated key in the result.

• Uses Object.assign to merge recursive results into the main result object.

Usage Example

const nested = {
  greeting: {
    morning: "Good morning",
    evening: "Good evening",
  },
  farewell: "Goodbye",
};

const flat = flattenObject(nested);
/*
flat = {
  "greeting.morning": "Good morning",
  "greeting.evening": "Good evening",
  "farewell": "Goodbye"
}
*/

createTranslationTable

export function createTranslationTable(
  langs: FlattenedObject[],
  langKeys: string[],
): TranslationTableRow[]

Description

Generates a translation table array from multiple flattened language objects. Each row corresponds to a translation key, with columns for each language's translated string.

Parameters

• langs: FlattenedObject[] — Array of flattened language objects, each representing translations for a language.

• langKeys: string[] — Array of language identifiers corresponding by index to the langs array (e.g., ['English', 'Vietnamese']).

Returns

• TranslationTableRow[] — An array of objects, each object representing a row with a translation key and translations for each language.

Implementation Details

• Uses a Set to collect all unique translation keys across all language objects.

• Iterates over the keys to build a row object.

• For each language, assigns the corresponding translation string or an empty string if the key is missing.

• Returns the array of rows, which can be consumed for display, export, or other processing.

Usage Example

const english = {
  "greeting.morning": "Good morning",
  "farewell": "Goodbye"
};

const vietnamese = {
  "greeting.morning": "Chào buổi sáng",
  "farewell": "Tạm biệt"
};

const table = createTranslationTable([english, vietnamese], ['English', 'Vietnamese']);
/*
table = [
  {
    key: "greeting.morning",
    English: "Good morning",
    Vietnamese: "Chào buổi sáng"
  },
  {
    key: "farewell",
    English: "Goodbye",
    Vietnamese: "Tạm biệt"
  }
]
*/

Important Implementation Details and Algorithms

• The flattening algorithm uses recursive depth-first traversal of the nested object.

• Keys are concatenated with dot notation (parentKey.childKey) to maintain the nested structure in a flat key.

• createTranslationTable uses a set union approach to collect keys from multiple language objects to guarantee all keys appear in the output table, even if missing in some languages.

• Missing translations are represented by empty strings to maintain table consistency.

Interaction with Other System Components

• This file likely interacts with:

  • Localization data loaders: receiving raw nested translation JSON objects per language.

  • Translation management interfaces: providing flat or tabular data for editors or export.

  • Export tools: enabling the translation table to be converted to CSV/XLSX.

  • Import tools: flattened objects can be restructured back to nested forms (not implemented here, but common in related utilities).

• It acts as a utility module in the i18n pipeline, abstracting the complexity of nested structures and multi-language alignment.

Visual Diagram

flowchart TD
    A[NestedObject Input] -->|flattenObject()| B[FlattenedObject Output]
    B --> C[createTranslationTable()]
    C --> D[TranslationTableRow[] Output]

    subgraph Flattening Process
        A --> B
    end

    subgraph Table Creation Process
        B --> C
        C --> D
    end

• Explanation:

  • The diagram shows the main workflow:

    • Nested objects are input to flattenObject.

    • Flattened objects are then inputs for createTranslationTable.

    • The final output is a translation table ready for further use.

Summary

until.ts is a focused utility module for:

• Flattening nested translation/localization objects into dot-notated flat objects.

• Building translation tables combining multiple languages into a uniform structure for UI or export.

Its functions are essential for managing complex nested translation data in multi-language applications, facilitating easier editing, comparison, and integration with translation tools.