better-i18n.com
Developer DocsHelp CenterChangelog

How do I create my first project?

Updated Aug 21, 2026Ali Osman Delişmen

A project holds the keys, languages, and settings for one app or site. Creating one takes a minute; the two things worth getting right are the source language and where your key ends up.

Create it #

  1. Sign in at app.better-i18n.com
  2. New Project
  3. Name it — this becomes the project's slug, so keep it short
  4. Pick the source language: the language your code is written in
  5. Add the languages you want to translate into
  6. Create

Create your project — enter a name and choose your source language

The source language is the one choice to think about. Every translation is produced from it, and every key's original text lives in it. You can change it later in Settings → CDN, but it is the reference point for everything, so start with the language you actually write.

Target languages are cheap to change — add and remove them from the Languages page whenever.

Your project identifier #

Every project is addressed as org/project — acme/dashboard. You will type it into your SDK config, your CLI config, and any API call.

Create an API key #

Settings → API Keys → Create Key.

Create API Key — give your key a name and click Create Key

Give it a name you will recognise in six months ("CI", "local dev") and choose an expiry: 3 months, 6 months, 1 year, or never. The list shows how long each key has left and warns you when one is within a month of expiring — a key that dies silently in CI is a bad afternoon.

The key is shown once. Copy it when it appears; you cannot read it again, only replace it.

Which key goes where #

ReadWriteSafe in a browser
CDN / delivery key✓—✓
API key✓✓No

The CDN key only fetches published translations, which are public data your visitors download anyway. The API key can change your project, so it belongs in a server environment variable or your CI secrets — never in client-side code, and never in a committed file.

If a secret key does end up somewhere public: revoke it on the API Keys page and create another. Revoking is immediate.

Point your app at it #

Bash
# .env
BETTER_I18N_PROJECT=acme/dashboard
BETTER_I18N_API_KEY=...
TypeScript
// The exact call depends on your framework — see the SDK guide
const i18n = createI18n({
  project: "acme/dashboard",
  defaultLocale: "en",
});

What's next #