Skip to content
docs

Your First Project

This walkthrough takes you from an empty account to a published translation project on the CDN. You won’t write any application code — that’s a separate step, covered in Consume translations.

By the end, you will have:

  • A Comvi project with a source language and two target languages
  • A handful of translation keys with values in all three languages
  • A published CDN URL that returns your translations as JSON

Walkthrough

Section titled “Walkthrough”

  1. Create your Comvi account and finish onboarding

    Go to app.comvi.io and sign up with email or Google. Signup kicks off a two-step onboarding:

    1. Name your first organization — the top-level container for your projects, members, and billing. You can rename it later.
    2. Create your first project — give it a name (e.g. acme-web) and pick the source language. English is pre-selected; pick whichever matches your source of truth.

    After both steps you land on the project dashboard.

  2. Add target languages

    In the project, go to Languages. Click Add Language and select the languages you want to support. For this tutorial, add two:

    • French (fr)
    • German (de)

    Locale codes usually use BCP 47 hyphenated form (pt-BR, zh-Hant, sr-Latn). For rare cases where a standard code doesn’t fit, you can also define a custom locale — see Languages. You can add more at any time.

  3. Create a few translation keys

    Go to the Translations page. Click Add Translation and create these four keys, entering a source (English) value for each:

    KeySource value
    greetingHello, {name}!
    welcome_messageWelcome to our application
    nav.homeHome
    nav.settingsSettings

    The {name} token is ICU MessageFormat — the platform validates it on save. See Core Concepts for the full syntax.

  4. Translate into target languages

    You have three ways to fill in values:

    • Type them manually. Click any cell in the French or German column and enter a translation.
    • Use machine translation. First configure at least one MT provider under Project Settings → Machine Translation (Google, DeepL, AWS, Azure, OpenAI, or Anthropic) and pick a primary. Then select keys in the translations table and open the Apply Machine Translation dialog to run a batch. See Machine Translation.
    • Import from a file. Skip the manual step if you already have translations — the platform currently imports .json files and .zip archives of them. See Import & Export.

    For this tutorial, enter these by hand so you see the editor flow:

    KeyFrenchGerman
    greetingBonjour, {name} !Hallo, {name}!
    welcome_messageBienvenue dans notre applicationWillkommen in unserer Anwendung
    nav.homeAccueilStartseite
    nav.settingsParamètresEinstellungen

    Notice that new values land in the Not reviewed state. This is intentional — a reviewer would normally check them before they ship.

  5. Mark translations as reviewed

    Since you’re both the translator and reviewer, click the status badge on each value and mark it Translated. In a larger team, a separate reviewer does this step. See Roles & Permissions for who can review what.

  6. Publish to the CDN

    Publishing lives under Settings → Content Deploy. Open it and:

    • Click Enable Content Deploy to turn auto-deploy on.
    • Pick the languages to include (all three).
    • Pick the namespaces (you only have default).
    • Under Filter by Status, check Translated so unreviewed values aren’t shipped. Leaving everything unchecked deploys all statuses.
    • Click Save Settings.

    Once enabled, translations auto-deploy on every save. To push the current state immediately, click Deploy Now next to the CDN endpoint. Within a few seconds your translations are available on the CDN.

  7. Verify the CDN URL

    On the same Settings → Content Deploy page, copy the CDN Endpoint URL shown above the Deploy Now button. Open a terminal and request the English bundle:

    Terminal window
    curl https://cdn.comvi.io/<your-distribution-id>/en.json

    You should see something like:

    {
      "greeting": "Hello, {name}!",
      "welcome_message": "Welcome to our application",
      "nav.home": "Home",
      "nav.settings": "Settings"
    }

    Swap en for fr or de to fetch the other languages.

  8. Create an API key for CLI or automation

    This is optional for the dashboard walkthrough. Published CDN URLs do not need an API key. If you plan to use the CLI, CI, or a custom script, go to Settings → API Keys, click Create API Key, give it a name (e.g. github-actions-ci), and copy the value — you won’t see it again.

What you built

Section titled “What you built”

You now have the complete producer side of a translation workflow:

  1. Source of truth — keys and translations live in the Comvi database
  2. Publication — translations are bundled as JSON and served from the global CDN
  3. Access — an API key your tools can use to automate the workflow

Nothing about this setup is tied to a specific framework or runtime. You can consume these translations from a web app, a mobile app, a backend service, a desktop app, or a static site generator.

Next steps

Section titled “Next steps”
Consume Translations Load your published translations into a web, mobile, or backend app.
Core Concepts Deeper dive into projects, namespaces, and the translation lifecycle.
Translation Lifecycle How values move from untranslated to translated, and where publish fits in.
Invite Your Team Add translators, reviewers, and developers with role-based access.
Machine Translation Scale translation work with automated first drafts.