If you’re starting with an empty project, the first step is to set up your language base by choosing which languages your app should support. This selection isn’t permanent. You can adjust it at any time and add or remove languages later as your project evolves.

Next, you define the default language. This is your source language, where you maintain the original content and from which translations are derived. BetterLocale Code uses this default language as a reference to create new entries cleanly, reliably detect missing values, and generate translations in a targeted way instead of blindly overwriting everything. This is especially useful during ongoing development, because it keeps a single, clear source of truth for wording and content.

If you’re not starting from scratch, you can import existing localization files. BetterLocale Code can read .strings, .xcstrings, and full .lproj folder structures. Existing keys and values are preserved, so you don’t have to begin with an empty list. From there, you can add languages, fill in missing translations, and fix inconsistencies without hunting through files in Xcode or a text editor.

This way you quickly end up with a clean, consistent localization setup, whether you’re starting fresh or cleaning up and continuing an existing project.

Next, you create your keys and manage them centrally within the project. Existing keys can be edited, renamed, or deleted at any time, depending on what you need.

When you create a new key, BetterLocale Code automatically adds it for all currently enabled languages. The values start out empty, so you only enter translations where you actually need them. This keeps the structure clean and consistent across languages from the beginning and prevents the common issue of a key being missing in one language later on.

You can change both the key name and the per-language values. All updates are applied directly to the project structure, without having to maintain multiple files or folders manually. If you delete a key, it’s removed across all languages, so no outdated entries are left behind in the project.

Once your keys and texts are complete in BetterLocale Code, you can generate translations directly through an AI service. The app currently supports OpenAI, DeepL, Gemini, Claude, and Perplexity. You can choose to translate everything or only missing or changed entries, so you don’t spend time or money on content that’s already done.

To use this, you’ll need an account with the provider and an API token. You enter that token in BetterLocale Code under Settings. It is stored only locally on your Mac and is never sent to us. Before you start, it’s worth running a connection test so you can immediately confirm that the token, model selection, and access are set up correctly. If the test fails, the most common causes are an invalid token, missing permissions, an incorrect endpoint, or the fact that no payment method has been added to your provider account yet.

Costs can vary significantly depending on the provider and model, but in many cases they’re far cheaper than traditional translation agencies, especially if you translate updates frequently. Some providers charge per character or “units,” others bill by tokens. With ChatGPT, text is split into tokens, and depending on the language and word length, even a few words can consume multiple tokens. Input and output are billed separately, meaning you pay for both your prompt (including any context) and the generated translation. In practice, more context and longer responses increase usage.

If you want to keep costs low, a few simple habits help: translate only what’s new or empty, provide only the context that’s truly necessary, and start by testing with a small set of entries before running large blocks of text.

Create an AI API Key and add it to the app

To use automatic translation and the AI chat in the app, you need an API key from an AI provider.
Think of it as a personal access code: the provider uses it to recognize that the request is coming from you, and bills usage through your account.

The app currently supports: OpenAI, Claude, DeepL, Gemini, and PerplexityAI.

Setup is very similar across all providers.

What you should know first
• API key = access code: You enter it in the app so it can send requests to the provider on your behalf.
• Costs are billed to you: The app sends the requests, but billing happens directly through your provider account.
• Billing is often required: Many providers only allow API requests after you add a payment method. Without billing, you’ll often get errors or be stuck in very small free limits.

Quick start: 5 steps to get set up

1. Create an account or sign in

Go to your provider’s website and sign in (or create a new account).

2. Create an API key

Look for a section like API, Developer, Dashboard, or API Keys and create a new key there.

3. Copy the key and store it safely

Copy the key immediately and store it somewhere safe, ideally in a password manager.

Important: many providers show the key in full only once.

4. Enable billing/payment

Add a payment method or enable billing. Otherwise, API requests often won’t work at all or will be heavily limited.

5. Paste the key into the app

Open the app → Settings → AI Providers → select a provider → paste the API key → Save

After that, you can start translations and use the integrated AI chat.

Provider setup (with direct links)

OpenAI (ChatGPT / OpenAI API)

1. Open the OpenAI dashboard:
https://platform.openai.com/
2. Create an API key:
https://platform.openai.com/settings/organization/api-keys
3. Set up billing/payment method:
https://platform.openai.com/settings/organization/billing/payment-methods

Tip: You often see the key in full only once. After that, it may be shown only partially.

Claude (Anthropic)

1. Open the Claude Console:
https://platform.claude.com/
2. In the console, go to Account Settings and create the API key there.
3. Enable billing in the console so you can use the API.

Note: This used to be handled partly via console.anthropic.com; it’s now being migrated/redirected to platform.claude.com.

Gemini (Google)

1. Open Google AI Studio (API Keys):
https://aistudio.google.com/app/apikey
2. If you don’t have a project yet: AI Studio often creates a default project automatically. Otherwise, select/import a Google Cloud project.
3. Create the API key and copy it.

Gemini API key documentation:
https://ai.google.dev/gemini-api/docs/api-key

PerplexityAI

1. Open Account/Settings:
https://www.perplexity.ai/account
2. In Settings, open the </> API tab and generate a key (“Generate API Key”).
3. Alternatively (depending on the UI), use the API portal:
https://www.perplexity.ai/account/api

Optional: API Groups are useful if you want to keep keys separate (for example, “Dev” and “Prod”).

DeepL

1. Open DeepL and sign in:
https://www.deepl.com/
2. Open Account → API Keys & Limits.
3. Click Create key, enter a name, confirm, and copy the key.

DeepL help article:
https://support.deepl.com/hc/en-us/articles/360020695820-API-key-for-DeepL-API

Notes on costs and privacy

• Using AI APIs is usually paid and billed directly through your provider account, typically based on text volume (tokens).
• The app sends only the content you select (for example, the text you want to translate) plus your instruction to the provider.
• Your API key is stored locally on your Mac in the Keychain and is not shared with third parties.

Security

Treat your API key like a password:
• Don’t share it and don’t commit it to public repositories.
• If you think the key is compromised, disable it in the provider dashboard and create a new one.
• If you use multiple devices or projects, it’s best to create a separate key per device/project so you can revoke access selectively without breaking everything.

BetterLocale Code gives you two ways to translate text. In both cases, you work with context so the translation isn’t done “blind,” but matches your app’s tone, audience, and writing style.

If you already use an external AI tool or prefer to review everything yourself, use the template approach. BetterLocale Code generates a clean translation request from your selected entries in the format “Key” = “Value”;. You can include guidance such as the desired tone (neutral, casual, technical), target audience (developers, end users), product name, UI style (short, menu-like), and rules for placeholders. You then copy this template into the tool of your choice, for example ChatGPT, Gemini, or DeepL. Afterward, you paste the translated lines back into BetterLocale Code. The app detects the keys, maps the values correctly, and updates the corresponding entries automatically. There’s no manual matching and no bouncing between files. This is ideal if you want maximum control and don’t want to rely on an API account.

If you want everything to stay in one workflow, you can translate directly inside BetterLocale Code via API. Here as well, you provide context such as tone, audience, and optional notes to keep translations consistent. Supported providers include OpenAI, DeepL, Gemini, Claude, and Perplexity. You’ll need an API key from the provider you choose, which is used to run and bill the requests. You also decide whether to translate everything or only new, changed, or empty entries. This saves time, reduces copy and paste, and writes results straight into your project data so you can keep working immediately.

BetterLocale Code does not calculate translation costs. Any costs come only from your AI provider and depend on your plan and the amount of text translated. That makes expenses predictable, especially when you translate only changes instead of re-translating everything.

In manual translation, the workflow is almost the same as API translation, except the actual translation step happens outside the app.

When you start Manual Translate, a dialog opens where you define the scope. You can provide context, such as the desired tone (neutral, casual, formal), target audience, product references, or guidance like “keep UI labels short” or “use informal/formal address.” Next, you choose what should be translated: everything, or only fields that are empty, new, or appear to have changed. This lets you control very precisely how much text is actually sent out.

After you confirm, BetterLocale Code automatically generates a ready-to-use translation prompt including your instructions and a list of the key-value pairs to translate. The prompt is copied straight to the clipboard, so you can paste it into any tool without extra editing.

Then you open ChatGPT, DeepL, Gemini, or another translation tool, paste the prompt, and run the translation. The important part is that the result must come back in the format

“Key” = “Value”;

with exactly one entry per line. The keys must not be changed, so BetterLocale Code can match each translation unambiguously.

Afterwards, copy the full result to the clipboard and paste it back into BetterLocale Code. The app parses the lines, matches them against your existing keys, and writes the translated values into the correct languages.

Manual translation usually takes a bit longer, but it’s ideal if you don’t want to connect a paid API service or if you intentionally want to work with different tools. If something is off when you paste the result, such as an invalid format, missing quotes, duplicate keys, or lines that can’t be matched, BetterLocale Code flags the affected entries as errors. That way you immediately see what needs to be fixed and avoid silently importing incorrect data into your project.

With automatic translation in BetterLocale Code, you have two options depending on how broadly you want to proceed. If you start the translation command from the base language, the app treats it as a full run and translates all selected target languages in one pass. If you run the command from a specific language instead, only that single language is translated, which is ideal when you want to catch up one language or review it in isolation.

After you start, a dialog opens where you can optionally provide additional context for the AI so the translations better match your project. For example, you can choose whether the wording should be more formal or more casual, define the audience you’re writing for, and specify product terms that should remain unchanged. You can also control whether only empty entries should be translated, so existing translations won’t be overwritten. Once you confirm the dialog, BetterLocale Code begins the translation process and works through entries one by one. Mapping is done via the keys, and progress is continuously updated per language.

If something goes wrong during translation, such as missing API permissions, an invalid configuration, network issues, or an unexpected response format, the app doesn’t fail silently. Instead, it collects error messages and shows them together at the end. This lets you quickly see which entries were affected and why, without having to manually trace the entire run.

You can tell a language is fully translated when the target language’s percentage matches the base language’s percentage, because both then have the same coverage of filled values. You’ll also see the number of remaining empty fields in the top-left of the table, so you can gauge at a glance whether gaps are still present. You can rerun the process at any time, for example after changes, to fill only newly added or still-missing translations without re-translating everything.

Once you’re done, you can export your localizations from BetterLocale Code straight back into your Xcode project. This puts the edited text exactly where Xcode expects it, including all languages, keys, and values.

Export as XCStrings (Strings Catalog)

If you work with .xcstrings, start by choosing your base language. This is the primary language Xcode uses as the reference for all other translations. Then export the file back to the original location in your project. That way, the existing file is replaced or updated, and Xcode picks up the changes immediately. This is especially handy when you’ve mainly filled in missing values or improved consistency and want to keep the Strings Catalog as the single source of truth in the project.

Export as .strings

If you prefer classic .strings files or you’re maintaining a legacy project, you can convert your data from XCStrings to the .strings format. Entries are written per language in the familiar key–value structure that many existing build setups and tools expect. This is also useful if your workflow is built around .strings, or if you simply don’t want to use Strings Catalogs.

Export as a .lproj folder structure

Alternatively, you can export localizations as separate language folders, using the traditional .lproj directory structure. Each folder contains the corresponding language files (for example, Localizable.strings). This matches Xcode’s classic layout and works well if you intentionally organize your project by language or manage multiple localization files per language.

Result in your project

No matter which export option you choose, your localization files end up in a format Xcode understands immediately. From there, you can test right away by switching the language on the simulator or device and verifying that all strings show up correctly.

In general, the setup always follows the same 5-step process:

1. Create an account or sign in
2. Create an API key
3. Copy the key immediately and store it securely (password manager)
4. Enable billing/payment (otherwise API requests often fail or stay limited by free tiers)
5. Paste the key into your app’s settings

OpenAI (ChatGPT / OpenAI API)

1. Sign in to the OpenAI API dashboard:

https://platform.openai.com/

2. Create your API key here:

https://platform.openai.com/settings/organization/api-keys

3. Add a payment method / enable billing (depending on your account):

https://platform.openai.com/settings/organization/billing/payment-methods

Prepaid (if you want to add credit):

Tip: You often only see the full API key once. After that, it may be shown only partially.

Claude (Anthropic)

1. Create/open your Claude Console account:

https://platform.claude.com/

2. In the console, go to Account Settings and create an API key there. (Anthropic’s docs describe it the same way: keys are generated in Account Settings.)

3. Set up billing in the console so you can use the API.

Note: This used to be handled partly via console.anthropic.com, which is now being migrated/redirected to platform.claude.com.

Gemini (Google)

1. Open Google AI Studio (API Keys page):

https://aistudio.google.com/app/apikey

2. If you don’t have a project yet: AI Studio often creates a default project + key for new users. Otherwise, select/import a Google Cloud project in AI Studio.

3. Create your API key there and copy it.

Gemini API key documentation overview:

https://ai.google.dev/gemini-api/docs/api-key

Perplexity

1. Sign in to Perplexity and open the account/settings page:

https://www.perplexity.ai/account

2. In Settings, look for the </> API tab. There you can generate a key (“Generate API Key”).

3. Depending on the UI, you may also use the API portal with API Keys / API Groups:

https://www.perplexity.ai/account/api

API Groups (if you want to separate keys cleanly, e.g. “Dev” / “Prod”):

DeepL

1. Sign in to your DeepL account:

https://www.deepl.com/

2. Go to Account → API Keys & Limits.

3. Click Create key, enter a name, confirm, and copy the key.

DeepL help article:

https://support.deepl.com/hc/en-us/articles/360020695820-API-key-for-DeepL-API

Important notes

• Treat your API key like a password. Don’t share it and never commit it to public repositories.

• If you think the key has leaked, disable it immediately in the provider dashboard and generate a new one (DeepL, for example, lets you do this directly in the key list).

• If you use multiple devices, it’s better to create one key per device/project so you can revoke access selectively without breaking everything.

In BetterLocale Code, you can send feedback directly from within the app without having to hunt for a contact address or gather details first.

When you choose the feedback command, BetterLocale Code opens your default email client and creates a new message with a prefilled subject line. That way your request is automatically categorized, and you can start writing right away.

This is especially useful if you have a question about a feature or a recommended workflow, want to submit a feature request, or need to report a bug. If you’re reporting an issue, it really helps if you briefly describe what you were trying to do, what actually happened, and what you expected instead. If possible, include a screenshot and mention which file type you were working with (.xcstrings, .strings, or .lproj).

When you change text in the base language, it’s often more than a simple typo fix. Meaning, tone, or context can shift and that can make existing translations in other languages inaccurate or simply outdated. That’s why BetterLocale Code gives you two clean options: you can intentionally reset translations after a change and recreate them, or you can apply the same base value across all languages.

If you update a value in the base language, it can be a good idea to clear the translations in the other languages so nothing stays wrong without anyone noticing. BetterLocale Code supports this in two ways: for meaningful edits, you’ll see a prompt asking whether the existing translations should be removed. And you can trigger the same cleanup manually anytime: switch to the base language in the language list, select the entry, and use the command “Delete translations for all languages.” The key remains unchanged, only the values in the other languages are cleared. This is handy because you immediately see what needs re-translation and because outdated translations don’t quietly linger in your project.

Typical cases include revised UI copy (tone, length, clarity), functional content changes (for example updated conditions or new features), or changes to placeholders and sentence structure where you explicitly want fresh translations.

Sometimes you want the exact opposite: a text should intentionally be identical across all languages. This often applies to content you don’t translate, such as URLs, brand or product names, model identifiers, or technical terms you want to keep consistent. In that case, use “Apply base value to all languages.” The app takes the value from the base language and writes it into every existing language. It saves time and keeps the content consistent everywhere.

For day-to-day work, there are also two commands that are constantly useful for maintenance and cleanup: “Copy to Clipboard,” which lets you copy entries individually or in bulk depending on context (for example for review or for an AI tool), and “Delete key including all values,” which removes an entry completely from the project, meaning the key and every language value. This is useful when a string is no longer used and you want to keep your project clean.

Once translations are available, it’s worth doing a quick spot check. Select an entry in the list and open the detail dialog via the context menu or the Edit Translations button. There you can review translations quickly and correct them immediately if needed.

The dialog shows three items stacked vertically: the translation in the currently selected language, a back-translation into the default language, and the original text in the default language. The back-translation is a handy sanity check. If it differs noticeably from the original in meaning, that’s often a sign the translation reads well but doesn’t capture the intent accurately.

This lets you review and “check off” entries efficiently or make targeted improvements without having to read large blocks of text every time. Especially with AI-generated translations, this dialog helps you squeeze out the last bit of quality and catch common issues early. It also includes actions that let you refine and adjust text directly within the dialog.

BetterLocale Code also includes an integrated AI chat that works like a classic chat assistant. You can ask questions directly inside the app and get help while you work, for example polishing wording (App Store text, UI strings, error messages), reviewing translations for tone and consistency, suggesting sensible key names and structures, or generating short explanations and variants without losing context.

Technically, the chat uses the same AI APIs as the translation features. That means the provider you’ve configured in BetterLocale Code (for example OpenAI, DeepL, Gemini, Claude, or Perplexity) is also used for chat. You get one consistent setup with the same credentials and the same rules.

Billing always goes through the respective provider and its pricing model. With token-based pricing, it’s important to know that input (the text you send) and output (the model’s response) are usually billed separately. Tokens are not words. As a rough rule of thumb, you can often estimate about 1 token ≈ 4 characters or roughly 0.75 words, but this can vary noticeably depending on language and content.

Just for orientation: In the OpenAI API, GPT-4.1 is priced at USD 2.00 per 1 million input tokens and USD 8.00 per 1 million output tokens, and GPT-4.1 mini at USD 0.40 (input) and USD 1.60 (output). Other providers and models may differ.

If you want to keep costs low, it usually helps to ask short, clear questions, only send the text that actually needs review (instead of entire files), use a smaller model for quick checks, and switch to a larger model only for sensitive or high-impact text.

The “Swift → KeyValue” feature helps you turn existing text definitions from your Swift code into a clean key-value format, so you can reuse them directly in BetterLocale Code.

Important: the app does not automatically scan Swift files in your project. You manually paste the relevant Swift code, or just specific snippets, into the input field. That’s intentional: you stay in control of what gets analyzed, and BetterLocale Code doesn’t need access to your project.

From the pasted content, the feature detects string constants where there is a stable mapping between a name and a string value. It then generates lines in the format „Key“ = „Value“;, which you can use as a foundation for your localization workflow, for example with .strings or .xcstrings. Typical sources include static let definitions, constants inside structs or enums, and centrally maintained text collections in containers such as Strings, L10n, Text, Copy, or similar.

It works best when the key and value clearly belong together, for example static let title = „Settings“. With string literals scattered throughout the code, like Text(„Settings“) or label.text = „Settings“, there’s usually no stable key that you’ll need later for localization. At that point the key would have to be guessed or inferred from context, which quickly leads to duplicate or conflicting keys, poor key names, and an inconsistent structure.

If you want reliable results, define your texts up front as constants or clearly named properties, such as static let settingsTitle = „…“, static let errorNetwork = „…“, or static let buttonSave = „…“. That way, BetterLocale Code can use the constant names as keys, output the string values cleanly as values, and produce a consistent key structure that stays easy to maintain.

If your code currently contains a lot of direct string literals, a good intermediate step is to move the most important texts into a central L10n or Strings structure first, and then run “Swift → KeyValue” to generate your localization base from there.

The “KeyValue to Code” feature regenerates clean Swift code from existing key-value entries, using a structured constants layout. This is especially useful if a project originally started with hardcoded UI strings in code, for example static let ok = „OK“ or static let loginTitle = „Sign In“.

When you later move to proper localization, you often want to keep that familiar structure in your code, just without the fixed text. Instead, the code should reference localization keys only. That’s exactly what “KeyValue to Code” does: BetterLocale Code generates the properties again and replaces the old string literals with the matching keys you maintain in your .strings or .xcstrings files.

Important: the app does not automatically scan Swift files in your project for this. You paste the relevant code snippet or a list of keys into the input field manually. This is intentional, so the feature stays fast, you keep full control, and no project-wide analysis is required.

Typical use cases include migrating from hardcoded strings to key-based localization with minimal manual effort, cleaning up and standardizing legacy constants files, and refactors where you build a clear “Strings” API, grouped by screens or features. It also makes code reviews easier, because UI text no longer lives in Swift files. The code stays stable with durable keys, while the actual wording changes only in your localization files.

Bottom line: you end up with a robust, maintainable setup. Your Swift code stays clean and consistent, and the real text lives centrally in your localization files, where you can translate it, review it, and version it properly.