> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# Internationalization (i18n)

> Multi-language support and localization in Fresh text editor

Fresh supports multiple languages for its user interface. The editor automatically detects your system locale, but you can also set your preferred language manually.

## Supported Languages

Fresh currently supports the following locales:

<CardGroup cols={3}>
  <Card title="English" icon="flag-usa">
    `en` - English (default)
  </Card>

  <Card title="Chinese (Simplified)" icon="flag">
    `zh-CN` - 简体中文
  </Card>

  <Card title="Japanese" icon="flag">
    `ja` - 日本語
  </Card>

  <Card title="Spanish" icon="flag">
    `es` - Español
  </Card>

  <Card title="French" icon="flag">
    `fr` - Français
  </Card>

  <Card title="German" icon="flag">
    `de` - Deutsch
  </Card>

  <Card title="Italian" icon="flag">
    `it` - Italiano
  </Card>

  <Card title="Portuguese (Brazilian)" icon="flag">
    `pt-BR` - Português (Brasil)
  </Card>

  <Card title="Russian" icon="flag">
    `ru` - Русский
  </Card>

  <Card title="Korean" icon="flag">
    `ko` - 한국어
  </Card>

  <Card title="Vietnamese" icon="flag">
    `vi` - Tiếng Việt
  </Card>

  <Card title="Thai" icon="flag">
    `th` - ไทย
  </Card>

  <Card title="Ukrainian" icon="flag">
    `uk` - Українська
  </Card>

  <Card title="Czech" icon="flag">
    `cs` - Čeština
  </Card>
</CardGroup>

<Note>
  The complete list of locale files is available in the [locales directory](https://github.com/sinelaw/fresh/tree/master/crates/fresh-editor/locales) of the Fresh repository.
</Note>

## Setting Your Language

There are three ways to configure your preferred language:

### 1. Using the Settings UI

The easiest method:

<Steps>
  <Step title="Open Settings">
    Navigate to **Edit → Settings...** from the menu bar.
  </Step>

  <Step title="Find Language Setting">
    Go to the **General** section.
  </Step>

  <Step title="Select Locale">
    Choose your preferred language from the dropdown.
  </Step>

  <Step title="Restart Fresh">
    Changes take effect after restarting the editor.
  </Step>
</Steps>

### 2. Configuration File

Edit your `~/.config/fresh/config.json`:

```json theme={null}
{
  "locale": "es"
}
```

Restart Fresh for the changes to take effect.

### 3. Command-Line Flag

Override the locale for a single session:

```bash theme={null}
fresh --locale ja
fresh --locale zh-CN
```

This takes precedence over the configuration file setting.

## Locale Priority

Fresh determines the active locale using this priority order (highest to lowest):

1. **Command-line flag**: `--locale <LOCALE>`
2. **Configuration file**: `"locale": "<LOCALE>"` in `config.json`
3. **System locale**: Detected from `LANG` environment variable
4. **Default fallback**: `en` (English)

<Accordion title="System Locale Detection">
  Fresh reads the `LANG` environment variable to detect your system locale:

  ```bash theme={null}
  echo $LANG
  # Example output: ja_JP.UTF-8, es_ES.UTF-8, etc.
  ```

  The language code is extracted from the locale string (e.g., `ja` from `ja_JP.UTF-8`).
</Accordion>

## What Gets Translated

When you change the locale, the following UI elements are translated:

* **Menu bar** - All menu labels and items
* **Command palette** - Command names and descriptions
* **Status bar** - Status messages and indicators
* **Prompts** - File open, save, search dialogs
* **Error messages** - User-facing error text
* **Settings UI** - Setting labels and descriptions
* **Help text** - In-app documentation

<Note>
  **What doesn't change:**

  * Your file contents (obviously!)
  * Plugin-provided text (unless the plugin supports i18n)
  * LSP messages from language servers
  * Log files and debug output
</Note>

## Plugin Translations

Plugins can provide their own translations to match your selected locale.

### For Plugin Users

Plugins that support i18n will automatically use your configured locale. No additional setup required!

### For Plugin Developers

To add translations to your plugin:

1. Create `.i18n.json` files alongside your plugin:
   ```
   ~/.config/fresh/plugins/my-plugin/
   ├── plugin.json
   ├── main.js
   ├── en.i18n.json
   ├── ja.i18n.json
   └── es.i18n.json
   ```

2. Structure your translation files:
   ```json theme={null}
   {
     "command.my_action": "My Action",
     "message.success": "Operation completed successfully",
     "error.not_found": "Item not found"
   }
   ```

3. Use translations in your plugin code:
   ```javascript theme={null}
   const message = fresh.t("message.success");
   ```

Fresh will automatically load the appropriate translation file based on the active locale.

## Contributing Translations

Want to add or improve a translation?

<Steps>
  <Step title="Find the Locale File">
    Locale files are in the Fresh repository:

    `crates/fresh-editor/locales/<locale>.json`
  </Step>

  <Step title="Edit or Create">
    * To improve existing: Edit the `.json` file
    * To add new language: Copy `en.json` and translate all strings
  </Step>

  <Step title="Test">
    Build Fresh and test your translations:

    ```bash theme={null}
    cargo run --bin fresh -- --locale <your-locale>
    ```
  </Step>

  <Step title="Submit">
    Create a pull request with your changes.
  </Step>
</Steps>

### Translation Guidelines

* **Keep it concise** - UI space is limited in a terminal
* **Match tone** - Fresh uses friendly, direct language
* **Test in context** - See how translations appear in menus and prompts
* **Preserve placeholders** - Variables like `{file}` must remain unchanged
* **Check key bindings** - Some terms reference keyboard shortcuts

## Encoding vs. Locale

<Warning>
  **Don't confuse locale with file encoding!**

  * **Locale (i18n)**: UI language (menus, messages)
  * **Encoding**: How file bytes are interpreted (UTF-8, GBK, etc.)
</Warning>

For file encoding support, see:

* [Text Encoding Guide](/features/encoding) - File encoding support (UTF-8, GBK, Shift-JIS, EUC-KR, UTF-16, etc.)

## Examples

<CodeGroup>
  ```bash Use Japanese UI theme={null}
  fresh --locale ja
  ```

  ```bash Use Spanish UI theme={null}
  fresh --locale es
  ```

  ```bash Check system locale theme={null}
  echo $LANG
  # Set if needed:
  export LANG=ja_JP.UTF-8
  fresh  # Will use Japanese
  ```

  ```json Set in config (French) theme={null}
  {
    "locale": "fr"
  }
  ```

  ```bash Test all locales theme={null}
  # Try each locale to see translations
  for locale in en es ja zh-CN fr de; do
    echo "Testing $locale..."
    fresh --locale $locale
  done
  ```
</CodeGroup>

## Troubleshooting

### Translations Not Appearing

1. **Verify locale code** - Check spelling (e.g., `zh-CN` not `zh-cn`)
2. **Restart Fresh** - Locale changes require restart
3. **Check config syntax** - Ensure `config.json` is valid JSON
4. **View effective config**:
   ```bash theme={null}
   fresh --cmd config show | grep locale
   ```

### Mixed Language UI

If some parts are translated but others aren't:

* **Normal**: Some dynamic content (like plugin text) may not be translated
* **LSP messages**: Language servers send messages in their own language
* **Incomplete translation**: Some strings may not be translated yet - consider contributing!

## See Also

* [CLI Commands](/reference/cli-commands) - Using `--locale` flag
* [Configuration](/configuration/overview) - Config file format
* [Text Encoding](/features/encoding) - File encoding (different from UI locale)