dictionary.js

Introduction

dictionary.js is a file that Lingo.dev Compiler generates at build time. It stores the application's translations in a format that can be efficiently loaded at runtime.

Note: All changes to the dictionary.js file should be committed to the repo.

Example File

This is an example of a (very minimal) dictionary.js file:

export default {
  version: 0.1,
  files: {
    "components/hero.tsx": {
      entries: {
        "3/declaration/body/0/argument/1/1": {
          content: {
            en: "Welcome to our app",
            es: "Bienvenido a nuestra aplicación",
          },
          hash: "a1b2c3d4e5f6...",
        },
      },
    },
  },
};

For a complete description of the available properties, see Schema Properties.

File Location

By default, the dictionary.js file is output to a src/lingo directory, relative to the location of the compiler's configuration (e.g., a vite.config.ts file).

To learn how to customize this location, see Compiler Options.

Loading the Dictionary

The lingo.dev package provides a number of loadDictionary functions. These functions are responsible for loading the dictionary for the user's current locale (based on the current value of the locale cookie).

Each variation of the function is intended to be used in different environments. This is an example of using the client-side version of the function:

<LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
  <App />
</LingoProviderWrapper>

You should only use the provided functions to load the dictionary, rather than trying to load the dictionary manually.

Editing the Dictionary

Although the dictionary.js file is auto-generated, it is editable. You can, for instance, manually change a translation by editing the translation content.

That said, if the source content changes, the manual edit will be overwritten, so it's usually more maintainable to use the data-lingo-override attribute.

Schema Properties

This section describes all of the properties found in a dictionary.js file.

version

Schema version identifier used for compatibility checking and future migrations.

• Type: number
• Required: Yes

files

Container object that organizes all translation entries by their source file paths. Each key represents a relative path from the source root (e.g., "components/hero.tsx", "pages/home.jsx").

• Type: object
• Required: Yes

files[filePath].entries

Container for all translation entries discovered in the specific source file. Each key is an AST-based identifier that uniquely identifies translatable content within the file.

• Type: object
• Required: Yes

files[filePath].entries[astKey].content

Maps locale identifiers to their corresponding translated strings. Contains translations for all configured locales in your project.

• Type: object
• Required: Yes

files[filePath].entries[astKey].hash

SHA-256 hash of the original source content used for change detection and cache invalidation. When the source content changes, this hash changes, triggering re-translation of the entry.

• Type: string
• Required: Yes