meta.json

Introduction

meta.json is a file that Lingo.dev Compiler generates at build time. It tracks all translatable content discovered in a React application, serving as an inventory that bridges build-time analysis with runtime translation.

Note: All changes to the meta.json file should be committed to the repo.

Example file

This is an example of a (very minimal) meta.json file:

{
  "version": 0.1,
  "files": {
    "components/hero.tsx": {
      "scopes": {
        "3/declaration/body/0/argument/1/1": {
          "type": "element",
          "hash": "a1b2c3d4e5f6...",
          "context": "",
          "skip": false,
          "overrides": {},
          "content": "Welcome to our app"
        }
      }
    }
  }
}

To understand what all of the properties mean, see Schema Properties.

File location

By default, the meta.json 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.

Schema Properties

This section describes all of the properties found in a meta.json file.

version

Schema version identifier used for compatibility checking and future migrations.

• Type: number
• Required: Yes

files

Container object that organizes all translatable scopes 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].scopes

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

• Type: object
• Required: Yes

files[filePath].scopes[astKey].type

Indicates whether the translatable content is from a JSX element's content or a JSX attribute's value.

• Type: "element" | "attribute"
• Required: Yes

files[filePath].scopes[astKey].hash

SHA-256 hash of the source content used for change detection. When the source content changes, this hash changes, indicating that retranslation may be needed.

• Type: string
• Required: Yes

files[filePath].scopes[astKey].context

Contextual information to help translators understand the content's purpose or location.

• Type: string
• Required: No

files[filePath].scopes[astKey].skip

Flag indicating whether this content should be excluded from translation.

• Type: boolean
• Required: Yes

files[filePath].scopes[astKey].overrides

Locale-specific translation overrides that bypass the normal translation process. Useful for brand names, technical terms, or custom translations.

• Type: object
• Required: Yes

files[filePath].scopes[astKey].content

The actual source text that needs translation, extracted from your React components.

• Type: string
• Required: Yes