Getting started

Quick Start Guide

Get up and running with langctl in under 5 minutes. This guide will walk you through creating your first project and getting translation files into your app.

Prerequisites

Before you begin, make sure you have:

• A langctl account (sign up at app.langctl.com)
• For CLI: Node.js 20+ installed
• 5 minutes of your time

Option 1: Using the Dashboard

Step 1: Sign Up & Create Organization

1. Go to app.langctl.com/signup
2. Enter your full name, email and password, then click Create account
3. Open the verification link we email you (it expires after 24 hours; you can resend it)
4. Enter your organization name (e.g., “My Company”) and create the organization

Step 2: Create Your First Project

1. From Home or Projects, click New Project
2. Fill in the form:
   • Project Name: “My First Project” (the slug the CLI uses is generated from it)
   • Description: “Learning langctl” (optional)
   • Default Language: English - the language you write source text in
   • Target Languages: add Spanish and French
3. Click Create Project

Step 3: Add Translation Keys

1. Open Translations in the sidebar (it shows the project selected in the sidebar’s project switcher)
2. Click Add Key
3. Fill in the form:
   • Key Name: home.welcome
   • Module: home (optional but recommended)
   • Description: Welcome message on homepage
   • English: Welcome to our app!
   • Spanish: ¡Bienvenido a nuestra aplicación!
   • French: Bienvenue dans notre application!
4. Save the key

Step 4: Add More Keys (Optional)

Let’s add a few more keys to make it more interesting:

Step 5: Publish Your Keys

1. Select the keys you want to publish (use the checkboxes)
2. Click Publish in the bar that appears at the bottom

Only published keys are included in exports and langctl pull.

Step 6: Export Translations

1. Open Import & Export in the sidebar and switch to Export
2. Select the format - for example i18n JSON or Flat JSON for web apps
3. Select the languages to export
4. Download the files

Your exported file will look like this:

{
"home.welcome": "Welcome to our app!",
"home.subtitle": "Get started now",
"auth.login": "Log In",
"auth.signup": "Sign Up"
}

Place the exported files in your project, named after their language (the dashboard downloads them as translations.en.json, …; langctl pull names and places files for you):

my-project/
├── public/
│   └── locales/
│       ├── en.json    ← Place here
│       ├── es.json
│       └── fr.json
└── src/
  └── ...

Option 2: Using the CLI

Step 1: Install the CLI

The CLI needs Node.js 20 or newer.

npm install -g langctl

Verify installation:

langctl --version

Step 2: Create an API Key

1. Log in to app.langctl.com
2. Go to API Keys in the sidebar
3. Click New API Key
4. Enter a name (“My CLI Key”) and choose its permissions - Translations Read and Write cover pull and push
5. Copy the key (shown only once!)

Step 3: Set Up Your Repository

In the root of your app’s repository, run:

langctl init

init asks for the API key (input is hidden), lets you pick the project, file format and file location, and writes a langctl.json you can commit:

{
"project": "my-first-project",
"format": "json",
"output": "src/locales/{lang}.json"
}

You can also skip the prompts with flags: langctl init --project my-first-project --format json --output "src/locales/{lang}.json".

Step 4: Pull Translations

langctl pull

This writes one file per language to the path in langctl.json:

+ src/locales/en.json  created
+ src/locales/es.json  created  3/4 translated
+ src/locales/fr.json  created  3/4 translated

Only published keys are included. Drafts stay out of your app until someone reviews and publishes them (use --include-drafts to override). AI translations that nobody has approved yet are left out as well, so your app falls back to the default language for them.

Step 5: Push New Strings

Add new keys to your source-language file (e.g. src/locales/en.json), then upload them:

langctl push --dry-run    # preview what would change
langctl push              # upload new keys from the source language file
langctl push --publish    # upload and publish them in one step

By default push uploads only the source language and only adds new keys. Use -l all to upload every language and --overwrite to replace existing translations.

Step 6: Add Keys from the Terminal (Optional)

langctl keys create my-first-project home.welcome \
--module home \
--description "Welcome message on homepage" \
--value en="Welcome to our app!" \
--value es="¡Bienvenido a nuestra aplicación!" \
--value fr="Bienvenue dans notre application!"

langctl keys create my-first-project auth.login \
--module auth \
--value en="Log In" \
--value es="Iniciar sesión" \
--value fr="Se connecter"

New keys are drafts until you publish them:

langctl keys publish my-first-project home.welcome auth.login

# or publish every draft key in the project
langctl keys publish my-first-project --all

Other Platforms

Pick a different format in langctl init, or pass it to pull directly. Each format has a default path that follows the platform’s layout:

langctl pull -f android    # res/values/strings.xml, res/values-es/strings.xml, …
langctl pull -f ios        # en.lproj/Localizable.strings, es.lproj/…
langctl pull -f arb        # lib/l10n/app_en.arb, lib/l10n/app_es.arb, …
langctl pull -f nested-json -o "public/locales/{lang}.json"

Run langctl formats to list every format and its default path.

Next Steps

Now that you have translation files, integrate them with your framework:

• React/Next.js: See Web Frameworks Guide

• Angular: See Web Frameworks Guide

• Vue: See Web Frameworks Guide

• iOS: See Mobile Apps Guide

• Android: See Mobile Apps Guide

• Flutter: See Cross-Platform Guide

• AI Translation - Automate translations with AI

• Module Organization - Organize large projects

• Team Collaboration - Invite team members

• CI/CD Integration - Automate with GitHub Actions

Even if you prefer CLI, the dashboard is great for:

• Visual translation editing
• Team member management
• Checking plan usage
• Reviewing AI translations

Check out the full CLI Reference for more:

• Managing projects, keys and languages
• Publishing and unpublishing keys in bulk
• Team management from the terminal (API key with the org:admin scope)
• --json output and exit codes for scripts

Add More Languages

langctl projects add-language my-first-project de ja

Import Existing Translations

Already have translation files?

langctl import my-first-project ./old-translations/es.json -l es

# or, with langctl.json set up, upload every language at once
langctl push -l all

Automate with CI

In CI there’s no login step — set the key as a secret environment variable (LANGCTL_API_KEY) and check that committed files are up to date:

- run: npx langctl@0 pull --check   # exit code 7 if committed files are out of date
env:
  LANGCTL_API_KEY: ${{ secrets.LANGCTL_API_KEY }}

See CI/CD Integration for the full workflow.

Troubleshooting

Authentication failed

Run langctl whoami to see which key is in use (LANGCTL_API_KEY, --api-key or the stored key), its organization and scopes. Make sure your API key:

• Starts with lc_
• Hasn’t been revoked
• Was copied correctly (no extra spaces)

Project not found

Use the project slug (URL-friendly name), not the display name. langctl projects list shows the slugs:

langctl pull my-first-project      # ✓ slug
langctl pull "My First Project"    # ✗ display name

Keys missing from pulled files

Make sure your keys are published — drafts are excluded from pull and export:

langctl keys list my-project --drafts      # see unpublished keys
langctl keys publish my-project key1 key2 key3
langctl pull

Get Help

Stuck? We’re here to help:

• CLI Help: Run langctl --help or langctl <command> --help
• Documentation: Browse the sidebar for detailed guides
• Email Support: support@langctl.com
• GitHub Issues: Report a bug

What’s Next?

Now that you’ve completed the quick start, dive deeper into:

1. Installation Guide - Detailed setup and configuration
2. Dashboard Guide - Master the web interface
3. CLI Reference - Learn all CLI commands
4. Platform Integrations - Integrate with your stack