# Formatted Chinese

Romanize and translate Chinese text without leaving your notes. Select some text, run a
command, and get it back as a formatted study layout — characters with Jyutping, Yale, or
pinyin, and a translation alongside.

Built for Cantonese learners first. Most romanization tools are Mandarin-only, and the ones
that handle Jyutping don't translate or lay anything out. Mandarin is supported too.

## What it does

- **Format selection** — replaces the selected text with the formatted result
- **Format entire note** — does the same for the whole note
- Romanization: **Jyutping**, **Yale**, **Yale (tone numbers)**, or **pinyin**
- Layouts: stacked lines, vertical split, horizontal split, three-section, translation only
- Targets: English, Chinese (Traditional / Simplified / Hong Kong), Italian, Japanese, and more
- Toggles for separators, character alignment, word compounds, and source/translation order

## Requirements and network use

This plugin is a client for a hosted service. It does not romanize or translate anything
locally.

- **No account needed to start.** Install, enable, and it works — you get the same free
  daily allowance the website gives an anonymous visitor. An API key from
  [formattedchinese.com/account](https://formattedchinese.com/account) raises that limit;
  sign-up is free and optional.
- **Your text is sent over the network.** When you run a command, the selected text — or the
  entire note — is sent to [formattedchinese.com](https://formattedchinese.com) to be
  translated and romanized, and the result is sent back. Nothing is sent until you run a
  command, and no other note content is read.
- **Translation runs on the operator's own hardware**, not a third-party AI provider.
- **Google Translate fallback asks first.** If a translation fails, it can be retried
  through Google Translate — which means sending that text to Google. By default the
  plugin asks before doing so, the same as the website, and dismissing the prompt declines.
  You can set **Google Translate fallback** to always or never in settings.
- **Daily limits apply.** Without a key, the allowance is counted against your network
  address and shared with the website, so one person has one allowance across both. A free
  account raises it; higher limits again require a paid account.
- Text is processed to produce your result and is not stored for any other purpose. See the
  [privacy policy](https://formattedchinese.com/privacy) and
  [terms](https://formattedchinese.com/terms).

## Setup

1. Install and enable the plugin.
2. Select some Chinese text and run **Format selection**. That is the whole setup.
3. Optional: pick your default target language, romanization, and layout in
   **Settings → Formatted Chinese**.
4. Optional: if you hit the daily limit, create a free account at
   [formattedchinese.com](https://formattedchinese.com/signup), generate an API key, and
   paste it into the same settings page.

## Usage

Open the command palette and run:

| Command | Action |
|---------|--------|
| Formatted Chinese: Format selection | Formats the selected text in place |
| Formatted Chinese: Format entire note | Formats the whole note |

Defaults come from settings, so day to day it's select, run, done.

## Install

Search **Formatted Chinese** in Obsidian under Settings → Community plugins → Browse, or
open the [directory listing](https://community.obsidian.md/plugins/formatted-chinese).

For a pre-release build, use [BRAT](https://github.com/TfTHacker/obsidian42-brat) pointed
at `formattedchinese/formatted-chinese-obsidian`, or copy `main.js` and `manifest.json`
from the [latest release](https://github.com/formattedchinese/formatted-chinese-obsidian/releases)
into `<vault>/.obsidian/plugins/formatted-chinese/`.

## Building from source

```bash
npm install
npm run build
```

## Support

Bugs and feature requests: open an issue. If you find the tool useful, you can
[support the server costs on Ko-fi](https://ko-fi.com/formattedchinese).

## License

MIT — see [LICENSE](LICENSE).