Getting Started with LangCTL: CLI-First Translation Management

LangCTL is a command-line tool for managing translations. It’s designed for developers who want localization to feel like a natural part of their development workflow, not a separate process requiring different tools and interfaces.

This guide explains why LangCTL exists, how it approaches translation management, and gives you a high-level view of the workflow. For detailed commands and options, see the official documentation.

Why LangCTL Exists

Most translation management tools were built for a world where developers and translators work in separate systems. Developers export files, upload them somewhere, translators work in a web interface, and developers eventually import the results.

This workflow makes sense for large organizations with dedicated localization teams. But for many teams—especially small startups, indie developers, and technical products—it creates unnecessary friction:

Constant context switching between terminal and browser
Translation files that don’t integrate cleanly with Git
Expensive per-seat pricing for features you don’t need
Complex setup for simple requirements

LangCTL takes a different approach. The command line is the primary interface. Translation files live in your repository. Git is the source of truth.

Core Principles

CLI-first, not CLI-only

The terminal is where developers work. LangCTL makes common operations available as simple commands:

langctl scan      # Find translation keys in code
langctl status    # See what's missing
langctl push      # Sync to remote
langctl pull      # Pull from remote

This doesn’t mean web interfaces are bad. LangCTL includes a dashboard for situations where visual interfaces help. But the default workflow doesn’t require opening a browser.

Git as source of truth

Translation files are code artifacts. They should be versioned, reviewed in pull requests, and maintained with the same rigor as any other source file.

LangCTL treats your repository as canonical. The remote server syncs with your files, not the other way around. This means:

Full history of translation changes in Git
Changes appear in diffs and code review
Branching strategies apply to translations
No separate “download latest” step

Simple by default, powerful when needed

Most translation work is straightforward: add keys, translate them, ship. LangCTL makes the common case fast and adds capabilities when you actually need them.

You don’t need to configure translation memory, approval workflows, or machine translation integration to get started. Those features exist, but they’re not prerequisites.

The Workflow

Here’s how LangCTL fits into typical development:

Initial setup

Install and initialize once per project:

# Install globally
npm install -g langctl

# Initialize in your project
cd your-project
langctl init

# Follow prompts to configure languages and file locations

This creates a configuration file and sets up your project structure.

Daily development

As you build features, you add translation keys to your code using your framework’s i18n library (react-i18next, vue-i18n, @angular/localize, etc.).

// In your code
const message = t('welcome.greeting');

Periodically (or before commits), scan for new keys:

langctl scan

This detects keys in your codebase and ensures they’re tracked.

Adding translations

Add translations via CLI:

langctl add "welcome.greeting" --en "Hello!" --es "¡Hola!"

Or edit translation files directly—they’re just JSON/YAML files in your repository.

Team collaboration

Sync changes with your team:

# Pull changes others have made
langctl pull

# Push your changes
langctl push

This keeps everyone’s local files in sync with the shared state.

Before deploying

Check translation status:

langctl status

This shows missing translations, warnings, and completeness by language. Integrate this into CI/CD to catch issues before deployment.

What You Get

Using LangCTL provides:

Speed: Adding a key is a single command, not a browser workflow.

Integration: Translations participate in your normal Git workflow—commits, diffs, pull requests.

Simplicity: Start with just files and commands. Add features as you need them.

Affordability: Pricing designed for small teams, not enterprise localization budgets.

Control: Your data lives in your repository in standard formats. You’re not locked in.

What LangCTL Isn’t

LangCTL is intentionally focused. It’s not:

A full translation memory system: No sophisticated reuse of previous translations (though basic suggestions exist)
A translator collaboration platform: Non-technical translators may prefer visual interfaces
An enterprise solution: Large teams with complex workflows may need more sophisticated platforms

If you need those things, tools like Lokalise or Phrase may be better fits. LangCTL is for teams where developers handle translations and want that work to feel native to their workflow.

Getting Started

Ready to try it?

# Install
npm install -g langctl

# In your project
langctl init

The initialization wizard guides you through configuration. Within a few minutes, you’ll have translation management set up.

For detailed documentation, configuration options, and advanced features, visit the LangCTL documentation.

Related reading: CLI-Based i18n Management explores the philosophy behind CLI-first localization in more depth.