# Add i18n to an Obsidian Plugin

Yes. An agent moves your Obsidian plugin's command names, settings labels and notices into locale files, picks the language with getLanguage(), and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-i18n/obsidian-plugin/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads where the plugin's text lives before it moves any of it. In a plugin made from obsidianmd/obsidian-sample-plugin, `src/main.ts` holds every user-facing string: the ribbon icon's `Sample` label, the `Status bar text`, three commands (`Open modal (simple)`, `Replace selected content`, `Open modal (complex)`), two `Notice` messages and the one-word text `SampleModal` writes into `contentEl`. `src/settings.ts` has the settings tab, with `Settings #1`, the `It's a secret` description and the `Enter your secret` placeholder passed to `Setting.setName`, `setDesc` and `setPlaceholder`. `manifest.json` declares `minAppVersion` 1.0.0 and `isDesktopOnly` false, `package.json` builds with `tsc -noEmit -skipLibCheck` then esbuild (`esbuild.config.mjs`, `format: 'cjs'`, `target: 'es2021'`, `obsidian` marked external), lints with `eslint-plugin-obsidianmd` under `eslint.config.mts`, and `package-lock.json` resolves the `latest` tag of `obsidian` to 1.12.3.

Then it checks what the API offers, because the plugin should follow the app's language rather than the operating system's. `node_modules/obsidian/obsidian.d.ts` declares `getLanguage(): string`, documented as the ISO code of the configured app language with `en` as the default and marked `@since 1.8.7`. That number matters: `minAppVersion` is 1.0.0, so a vault on an older app would load the plugin and throw at startup. The agent raises `minAppVersion` to 1.8.7, adds the entry to `versions.json` so older apps keep the last compatible release, and notes it in `README.md`, which `AGENTS.md` asks for whenever a newer API is used.

It writes `src/i18n/en.ts` as a typed object (`commands.openModalSimple`, `settings.secret.name`, `notices.click`, `modal.body`), a `src/i18n/index.ts` that exports a `t(key)` function with `Locale = typeof en` so a missing key in another language is a TypeScript error under the `strict` and `noUncheckedIndexedAccess` settings in `tsconfig.json`, and one file per locale the prompt names, falling back to English for any string a locale lacks. `main.ts` keeps its command `id` values (`open-modal-simple`, `replace-selected`, `open-modal-complex`) untouched, since `AGENTS.md` treats ids as stable API, and passes `t('commands.openModalSimple')` as each `name`. The settings tab, the ribbon label, the status bar text, both notices and the modal body go through the same function, and `getLanguage()` is read once in `onload`, after `loadSettings`, so a language change takes effect on reload like the app's own.

The locale files are plain modules, not JSON fetched at runtime, so the bundle stays a single `main.js` as the release workflow and `AGENTS.md` require, and no network request is added. The agent runs `npm ci`, `npm run build` and `npm run lint` in its sandbox; the lint config's `obsidianmd` rules cover sentence case for command and setting names, so each translated string is checked the same way the English one is. It copies `main.js`, `manifest.json` and `styles.css` into a throwaway vault's `.obsidian/plugins/sample-plugin/` only to confirm the files land where the manual install expects them; it cannot open Obsidian, and the pull request says so.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add translations to this Obsidian plugin for English and German. Read manifest.json, versions.json, package.json, package-lock.json, tsconfig.json, eslint.config.mts, esbuild.config.mjs, AGENTS.md, src/main.ts and src/settings.ts first, and check obsidian.d.ts in node_modules for getLanguage and the version it was added in. Create src/i18n with a typed English locale, a German locale that must define every key, and a t() helper that falls back to English; move every command name, ribbon label, status bar text, notice, modal text and settings label, description and placeholder through it, and keep every command id unchanged. Read getLanguage() once in onload. Raise minAppVersion to the version getLanguage requires, add the matching versions.json entry and mention the requirement in README.md. Run npm ci, npm run build and npm run lint, and open a pull request that lists every string you moved and its German translation. Do not add a runtime dependency or any network call.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `src/i18n/index.ts`, `src/i18n/en.ts` and `src/i18n/de.ts`, edits `src/main.ts` and `src/settings.ts` to call `t()`, and changes `manifest.json`, `versions.json` and `README.md` for the new `minAppVersion`. Its description is a table of every key with its English and German text and the file it came from, followed by the `npm run build` and `npm run lint` output.

A reviewer with German reads the translations, since the agent wrote them and tone in a settings pane is a judgment call. They also check that `versions.json` maps the new plugin version to `1.8.7` and the previous one to `1.0.0`, that no command `id` changed, and that strings `eslint-plugin-obsidianmd` flags for casing were fixed in the locale file rather than suppressed.

## Run it on every new locale request

A plugin author who receives a translation request as a GitHub issue adds an automation to the Project with a `github` trigger on `issues.labeled` and the label `i18n`, and this prompt. The trigger appends the issue after the prompt, so the agent reads the language from the issue ("Add Japanese" adds `src/i18n/ja.ts` and nothing else) while the prompt text stays fixed. Only an issue labelled by an owner, member or collaborator fires it, and the automation runs at most `max_runs_per_hour` times in an hour.

An author with several plugins forked from the sample sends this body once per repository from their own machine or server, each a `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own `main.ts`: a plugin with a `View` subclass gets its `getDisplayText` string keyed too, and one already on `minAppVersion` 1.8.7 or later gets no manifest change.

## Why run it on Rush?

Moving strings out of `main.ts` is mechanical but unforgiving: one literal left behind stays English in every language, and one API call a vault's app version does not have breaks the plugin at load. In its sandbox the agent reads `obsidian.d.ts` for the exact `@since` version, builds with the same `tsc` and esbuild steps the release workflow uses, and lints every translated string with the Obsidian rules, so the pull request comes with that evidence.

The run keeps every command and its output, from the `npm ci` to the lint result, so a reviewer can see how each key was chosen. An author maintaining several plugins runs the same request across all of them at once instead of repeating the move by hand.

## Frequently asked questions

### Why raise minAppVersion?

Because `getLanguage()` is marked `@since 1.8.7` in `obsidian.d.ts`, and the sample manifest says 1.0.0. An app older than 1.8.7 would load the plugin and fail in `onload`. Raising the minimum and recording it in `versions.json` lets older apps keep installing the last release that worked for them, which is what that file is for.

### Does it change command ids or settings keys?

No. The command ids `open-modal-simple`, `replace-selected` and `open-modal-complex` stay as they are, so hotkeys users assigned keep working, and `MyPluginSettings.mySetting` keeps its name so `data.json` loads unchanged. Only the `name`, `setName`, `setDesc` and `setPlaceholder` arguments move to `t()` calls.

### Why TypeScript modules instead of JSON files?

The plugin ships as one bundled `main.js`, and `AGENTS.md` asks for no unbundled runtime files; esbuild inlines imported modules but a JSON file read at runtime would need to be shipped and located separately. Typing the English object and deriving `Locale` from it also makes a missing German key a compile error under the `strict` settings in `tsconfig.json`.

### What if the app language has no locale file?

The `t()` helper looks the key up in the locale that matches `getLanguage()` and falls back to English for any key that locale lacks, and to English entirely when there is no file for that language. A regional code such as `pt-BR` is tried as given and then as `pt`, so one Portuguese file serves both.

### Can the agent test this in Obsidian?

Not in the app itself. The sandbox has no Obsidian install, so the run builds, lints and places the three release files in a vault folder to confirm the layout. The pull request says exactly that, and the reviewer's manual reload with the app language set to German is the final check.

## More Obsidian plugin jobs

- [Add a GitHub Release Workflow to an Obsidian Plugin](https://getrush.ai/run/add-release-workflow/obsidian-plugin/)
- [Review Pull Requests on an Obsidian Plugin](https://getrush.ai/run/review-pull-requests/obsidian-plugin/)
- [Upgrade npm Dependencies in an Obsidian Plugin](https://getrush.ai/run/upgrade-npm-dependencies/obsidian-plugin/)

## The same job on other stacks

- [Add i18n with Gettext to a Phoenix LiveView App from a Linear Issue](https://getrush.ai/run/add-i18n/phoenix-liveview/)
- [Add i18n to a React App from a Linear Issue](https://getrush.ai/run/add-i18n/react/)
- [Add i18n to a React Router App](https://getrush.ai/run/add-i18n/react-router/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
