Namespaces

A namespace partitions a project's translations so a client fetches and stores only the slice it actually renders, instead of the whole project. This is the fix for the browser storage quota error (Setting the value of 'i18n-keyless-translations' exceeded the quota) and it cuts the amount of data each screen downloads.

A namespace is just a string you attach per translation — for example "checkout", "settings", or one per screen. It is an organizational / fetch partition, not a semantic key: the same source text can live in several namespaces with the identical translation, and that's fine. To disambiguate meaning (e.g. Retour as "Back" vs "Return"), keep using context — namespaces and context are independent.

info

The reserved default namespace is the literal string "default". If you don't set a namespace anywhere, everything lives in "default" and behaves exactly as before — existing projects need no changes.

Per-call namespace

Attach a namespace to a single translation.

React (web)

import { I18nKeylessText, getTranslation } from "i18n-keyless-react";

  return (
    <I18nKeylessText namespace="checkout">
      Pay now
    </I18nKeylessText>
  );
}

import { getTranslation } from "i18n-keyless-react";

  return (
    <p>
      {getTranslation("Pay now", { namespace: "checkout" })}
    </p>
  );
}

React Native

import { I18nKeylessText } from "i18n-keyless-react";

  return (
    <I18nKeylessText namespace="checkout">
      Pay now
    </I18nKeylessText>
  );
}

import { getTranslation } from "i18n-keyless-react";

  return (
    <Text>
      {getTranslation("Pay now", { namespace: "checkout" })}
    </Text>
  );
}

Node.js

warning

awaitForTranslation NEED to be awaited, to prevent 429 to happen.

import { awaitForTranslation, type Lang } from 'i18n-keyless-node';

async function renderCheckout(user) {
  // ...
  const label = await awaitForTranslation(
    "Pay now",
    user.lang as Lang,
    { namespace: "checkout" }
  );
  // ...
}

A global default namespace

Set defaultNamespace in init() to apply a namespace to every call that doesn't specify one. Per-call namespace always overrides it.

import * as I18nKeyless from "i18n-keyless-react";

I18nKeyless.init({
  API_KEY: "YOUR_API_KEY",
  storage: window.localStorage,
  defaultNamespace: "app-ui",
  languages: {
    primary: "en",
    supported: ["en", "fr", "es"],
  },
});

Transient, memory-only namespaces

For high-cardinality or short-lived namespaces (e.g. one per discussion or per document), add unpersistedNamespace. The namespace's translations stay in memory only: never written to storage, never reloaded at boot — so they add zero storage weight.

React (web)

import { I18nKeylessText, getTranslation } from "i18n-keyless-react";

  return (
    <I18nKeylessText namespace={`discussion-${id}`} unpersistedNamespace>
      {message}
    </I18nKeylessText>
  );
}

import { getTranslation } from "i18n-keyless-react";

getTranslation(message, { namespace: `discussion-${id}`, unpersistedNamespace: true });

React Native

import { I18nKeylessText } from "i18n-keyless-react";

  return (
    <I18nKeylessText namespace={`discussion-${id}`} unpersistedNamespace>
      {message}
    </I18nKeylessText>
  );
}

tip

Reusing a source text across namespaces never costs you an extra AI translation: if the string was already translated under any namespace, the backend copies that translation into the new namespace instead of re-translating.