Setting Up Your Project

Getting started guide to setting up Localhero.ai for production use.

Setup with CLI

Run the init command in your project directory. The CLI guides you through each step. 

npx @localheroai/cli init
1

API Key

Enter your API key when prompted. Get one from your account settings. The entered API key will be saved to .localhero_key and added to .gitignore.

2

Project

Create a new project or select an existing one from your organization. The project will hold your translation keys and settings, and can be viewed on localhero.ai once setup is complete.

3

Languages

Set your source language (translate from) and target languages (translate to). Enter target languages as a comma-separated list, e.g. sv,de,fr. Language codes must match your translation file names. If your source language file is called en-US.yml, use en-US as the source language.

Examples:

  • en.yml → use en
  • en-US/common.json → use en-US
  • pt_BR.json → use pt_BR
4

Translation files

The CLI detects your framework (Rails, Next.js, React, Django, etc.) and suggests where your translation files are located. Confirm or adjust the path.

5

GitHub Actions (optional)

You will be prompted to set up GitHub Actions for automatic translations on pull requests. This is optional but recommended for a smooth workflow. It creates the GitHub workflow file at .github/workflows/localhero-translate.yml. For the GitHub Action to work you'll need to add your API key to your repository secrets as LOCALHERO_API_KEY.

6

Import translations

Import your existing translation files to the dashboard. This uploads your current keys and translations so they're available for editing and inform future AI translations for consistency.

Setup complete

You should now have:

  • • Your project in the dashboard with your translation keys
  • • localhero.json in your project root
  • • (Optional) .github/workflows/localhero-translate.yml for automatic translations

Create a PR with the new files and you're ready to start translating 🎉

Configure Translation Settings

Configure how AI translates your content, to ensure they match your brand voice and consistency.

Where: Go to your project in the dashboard → Settings → Translation to configure these settings.

Brand Name

The main name for the product this project represents. The AI will never translate this name. If you have additional product names or terms that shouldn't be translated, add them to the glossary.

Acme Dashboard

Style Guide

Instructions that shape how translations read. Be specific about your voice and formatting rules. The more detail you provide, the more consistent your translations will be. 

# Style Guide

## About the product
Acme Dashboard is a B2B engagement analytics platform
for product managers and growth teams. Users are
technical but not developers.

## Writing style
- Use active voice
- Second person ("you") not third person ("the user")
- Clear and direct, avoid jargon and marketing speak
- No exclamation marks except for achievements

What to include:

  • • About the product and target audience
  • • Writing style do's and don'ts
  • • Language-specific preferences

Tone of Voice

Sets the overall feel of translations. Works together with your style guide.

  • Professional — Business-appropriate and formal. A great general choice that works in many settings like B2B SaaS.
  • Friendly — Warm and approachable
  • Informal — Casual and conversational
  • Technical — Precise and detailed
  • Casual — Relaxed and colloquial

Length Preference

Controls whether translations tend toward brevity or completeness.

  • Follow Source — Match original content length. A good default for most projects.
  • Shorter Texts — Compact texts that get to the point
  • Longer Texts — Detailed and descriptive content

Set Up Glossary

The glossary contains terms that need special handling during translation. This helps maintain consistency and handle edge cases.

Where: Go to your project in the dashboard → Settings → Glossary to add terms.

When to Add Terms

Add terms to your glossary when they:

  • • Are brand or product names
  • • Need to stay consistent across languages
  • • Have special technical meaning
  • • Should never be translated

Usage Instructions

When adding a term, include instructions about how it should be handled during translation.

Examples:

  • Product name: "This is a product name and should never be translated"
  • Technical term: "This is a parameter in a function, do not translate it"
  • Consistent term: "Always translate as 'Tableau de bord' in French"

Example Translations (optional)

You can provide example translations for specific languages to give the AI better guidance. This is useful for terms that should be translated consistently across your project.

Need help? Drop us a line at hi@localhero.ai