Strings & keys

This page explains how translation keys work in Translatable, how strings are counted, and how to structure your keys in a way that scales.

What is a key?

A key is a stable identifier used to reference a piece of translatable text in your application.

Examples:

COMMON.SAVE
ACCOUNT.AVAILABILITY.OpeningHours
ERRORS.FORBIDDEN

Keys are not shown to end users — they are used by your app to look up the correct translation at runtime.

What is a string?

A string is one translation value in one language.

In other words:

1 key × 1 language = 1 string

Example:

Key: COMMON.SAVE
Languages: en, fr, de

Strings used:

en = "Save"
fr = "Enregistrer"
de = "Speichern"

Total: 3 strings

How strings are counted

Strings are counted based on stored translation values.

These count:

A key with a value saved for a language
The same key translated into multiple languages (each language counts separately)

These do not count:

Empty values
Previous versions / history of values
Metadata such as notes or descriptions

You can always see your current usage in the workspace data usage view.

Empty values

When you:

Create a new key, or
Add a new language to a project

Translatable creates empty values for that key-language combination.

Empty values:

Do not count as strings
Only start counting once a value is saved

This allows you to prepare structure without immediately increasing usage.

Key structure

Keys are typically written using dot notation to represent hierarchy.

Example:

ACCOUNT.AVAILABILITY.OpeningHours

This helps with:

Grouping related strings
Filtering and searching
Exporting structured JSON files

There is no strict depth limit, but shallow, consistent structures are easier to maintain.

Key naming best practices

Use UPPERCASE or camelCase, but be consistent
Avoid including language names in keys
Avoid including dynamic values (numbers, IDs)
Prefer semantic meaning over UI position

Good examples:

COMMON.CANCEL
ACCOUNT.STATUS.Active
FORM.ERRORS.RequiredField

Renaming keys

Renaming a key:

Updates all translations for that key
Does not increase string usage
May require updating references in your codebase

Renaming keys does not affect billing, but it does affect your app code.

Deleting keys

Deleting a key:

Deletes all translation values for all languages
Immediately reduces string usage
Cannot be undone

Use this carefully, especially in production projects.

JSON export structure

When exporting to JSON, you can choose how your keys are structured:

Nested JSON

Dot-separated keys are converted into nested objects. This is the default for most modern frameworks.

Example key: ACCOUNT.AVAILABILITY.OpeningHours

Exports as:

{
  "ACCOUNT": {
    "AVAILABILITY": {
      "OpeningHours": "9–5"
    }
  }
}

Flattened JSON

Keys are kept exactly as they are written, which is often required for specific libraries or simple key-value lookups.