Lingo Studio for Obsidian

An English-reading companion plugin for Obsidian. Select a word to look it up, select a sentence to ask the AI — all from a clean right-side panel. Local-first, lightweight, no backend server.

Lingo Studio turns Obsidian into a focused English-learning workspace. It keeps dictionary lookups, AI explanations, flashcards, and readability stats inside the app you already use for notes — so you stop alt-tabbing to browser dictionaries and chat tools while reading.

🇨🇳 中文：Lingo Studio 把 Obsidian 变成一个专注的英语学习工作区。查词、AI 讲解、闪卡、可读性统计都留在你本来就用来记笔记的软件里——读英文时不必再切到浏览器词典和聊天工具。

---

Table of Contents

• What problem does it solve?
• Who is it for?
• Features
• How it works
• Installation
• Build from source
• Configuration
• Privacy & your data
• FAQ / 常见问题
• License

---

What problem does it solve?

English learners who read inside Obsidian constantly break their flow: copy a word, switch to a dictionary tab, copy a sentence, paste it into a chatbot, then forget to save anything. Lingo Studio removes that friction. The lookup, the AI explanation, and the difficulty score all live in a single right-hand panel that stays in sync with the note you are reading.

Key pain points it addresses:

• Context-switching — dictionary + AI chat + flashcards in one panel, no browser needed.
• No saved vocabulary — looked-up words become flashcards with one click.
• Unmeasured difficulty — every note shows its Total words / SMOG / FRE so you know how hard the text is.
• Privacy anxiety — your LLM key never leaves your vault; requests go straight from Obsidian to your provider.

🇨🇳 中文：在 Obsidian 里读英文的人，总是被迫打断心流——查词要开浏览器，问 AI 要切到聊天工具，还常常忘记保存。Lingo Studio 把查词、AI 讲解、闪卡、难度评分都收进同一个右侧面板，并随当前笔记自动同步。它解决的是：频繁切换工具、词汇没沉淀、文章难度没概念、以及隐私顾虑（密钥只存在你的 vault 里）。

Who is it for?

• English learners building vocabulary from articles, books, and papers.
• Students who annotate readings in Obsidian and want instant definitions + AI help.
• Researchers / academics reading English material who need a difficulty read on a text.
• Writers who want a lightweight, private AI editor for phrasing, grammar, and translation.
• Anyone who prefers a local-first, no-telemetry tool over cloud note apps.

🇨🇳 中文：适合用 Obsidian 读英文、积累词汇的学习者；需要对选中内容即时讲解/翻译/润色、又不想把数据交给云端工具的人。

---

Features

flowchart TD
    A[Lingo Studio Panel<br/>Right sidebar] --> B[Dictionary Tab]
    A --> C[Cards Tab]
    A --> D[Chat Tab]
    A --> E[Readability Header<br/>Total words · SMOG · FRE]

    B --> B1[Word lookup · dictionaryapi.dev]
    B --> B2[Phonetic + definitions]
    B --> B3[＋ Flashcard button]

    C --> C1[Word-only chips · wraps by width]
    C --> C2[Per-note: A's words show on A only]
    C --> C3[Click chip → Dictionary tab]

    D --> D1[AI chat · OpenAI-compatible]
    D --> D2[Ask AI about current note]
    D --> D3[Selection menu: Ask / Explain / Grammar / Translate / Copy]

    E --> E1[Auto-recalculates on page switch]
    E --> E2[↻ manual recalc button]

• 🔤 Dictionary — select a single word and the panel shows its phonetic and definitions (free dictionaryapi.dev, no API key). An LLM fallback kicks in only when you have a key set and the online source fails.
• 🗂️ Cards — looked-up words become flashcards with one click (＋ Flashcard). The Cards tab shows them as word-only chips that wrap to fit the panel width, and is scoped to the current note — a word you add while reading note A only appears in the Cards tab when note A is active, never on other notes. Click any chip to open its definition in the Dictionary tab. The very same chip view also replaces the flashcards.md note itself (read-only).
• 💬 Chat — an AI chat tab backed by any OpenAI-compatible endpoint (OpenAI, DeepSeek, local LLMs). "Ask AI about current note" sends the active note's text; the customizable selection menu lets you Explain, check Grammar, or Translate a selected sentence.
• 📊 Readability — a header shows Total words / SMOG / FRE for the current note, computed offline with no data files. It auto-recalculates when you switch notes and has a ↻ button for a manual refresh.
• 🪶 Lightweight & local-first — only the obsidian API as a hard dependency; no COCA data, no backend, no telemetry.
• 🔑 Your keys stay local — LLM calls go directly from Obsidian to your endpoint via requestUrl (CORS-safe). The API key is stored in the vault's plugin data, never in this repository.

🇨🇳 中文（功能）：词典——选中单词即查音标与释义（免费 dictionaryapi.dev，无需密钥；配置了密钥且在线失败时回退到 LLM）。闪卡——查词后点「＋ Flashcard」一键存卡；Cards 标签页把单词以只显示单词的词块展示、按面板宽度自动换行，且按当前笔记隔离：在 A 笔记加的词只在 A 出现，不会串到其他笔记。点击任意词块即跳到右栏词典查词；同样的词块视图也会替换 flashcards.md 笔记本身（只读）。对话——对接任意 OpenAI 兼容接口（OpenAI / DeepSeek / 本地模型），可「就当前笔记问 AI」，选中文字后弹出可自定义的菜单（讲解 / 语法 / 翻译 / 复制）。可读性——顶部显示当前笔记的「总词数 / SMOG / FRE」，纯本地计算，切页自动重算，并有 ↻ 手动重算。轻量且本地优先——仅依赖 obsidian API，无后端、无埋点。

---

How it works

flowchart LR
    U[User selects text<br/>inside english-files/] --> S{Lingo Studio}

    S -->|single word| D[Dictionary lookup<br/>dictionaryapi.dev]
    S -->|sentence / phrase| M[Selection menu]
    M --> C[Chat tab → AI request]

    C --> API[Your LLM endpoint<br/>OpenAI / DeepSeek / local]
    K[(API key stored<br/>locally in vault)] --> API
    API -->|requestUrl · CORS-safe| R[Response in right panel]

    D --> R

1. You select text inside a note under the english-files/ folder.
2. A single word opens the Dictionary tab instantly; any selection also shows the customizable AI menu.
3. AI actions send the selection (prefixed with your instruction) to your configured LLM endpoint.
4. Chat logs are saved into english-files/chat/ by timestamp; flashcards into english-files/flashcard/flashcards.md.

🇨🇳 中文（原理）：在 english-files/ 目录下的笔记里选中文字即可触发。单词直接查词典；句子/短语弹出可自定义的 AI 菜单，把选中内容（带上你的指令）发往你配置的 LLM 接口。对话记录按时间戳存入 english-files/chat/，闪卡存入 english-files/flashcard/flashcards.md。

---

Installation

Option A — Manual install (no build needed)

1. Download the lingo-studio/ folder (it already contains main.js, manifest.json, styles.css).
2. Copy it into your vault:

   <your-vault>/.obsidian/plugins/lingo-studio/
   

   The folder must be named lingo-studio — it has to match the plugin id in manifest.json, or Obsidian will not load it.

3. In Obsidian: Settings → Community plugins → enable "Lingo Studio".
4. Open the panel with the ribbon icon (book) or the command Open Lingo Studio panel.
5. (Optional) Add your LLM API key under Settings → Lingo Studio → LLM (Ask AI) so the Chat tab works.

Option B — Build from source (see below) if you want the latest code.

🇨🇳 中文（安装）：把仓库里的 lingo-studio/ 文件夹整个复制到 <你的仓库>/.obsidian/plugins/lingo-studio/（文件夹名必须叫 lingo-studio，要与 manifest 里的 id 一致）。然后在 Obsidian「设置 → 社区插件」中启用 Lingo Studio。可用 ribbon 图标或命令「Open Lingo Studio panel」打开面板。想用对话功能，就在「设置 → Lingo Studio → LLM (Ask AI)」里填入你的 API Key。

Build from source

Requires Node.js 18+.

npm install        # install dev dependencies (esbuild, typescript, obsidian types)
npm run build      # tsc type-check + esbuild -> lingo-studio/main.js

Then copy the lingo-studio/ folder to your vault as shown above. After editing source, re-run npm run build and reload Obsidian (Cmd/Ctrl + R).

🇨🇳 中文（从源码构建）：先 npm install，再 npm run build（会做类型检查并用 esbuild 生成 lingo-studio/main.js）。改完源码后重新 build 并重载 Obsidian 即可生效。

---

Configuration

Open Settings → Lingo Studio:

Setting	What it does
LLM · API key	Your OpenAI / DeepSeek / compatible key. Stored locally in the vault only.
LLM · API base	OpenAI-compatible base URL (default https://api.openai.com/v1). For DeepSeek use https://api.deepseek.com/v1.
LLM · Model	e.g. gpt-4o-mini, deepseek-chat.
Ask system prompt	System prompt for the "Ask" action and the dictionary "Ask AI" button.
Dictionary · Source	Online (free dictionaryapi.dev) or LLM fallback.
Folders	Where chat logs and flashcards are saved (default english-files/chat, english-files/flashcard, file flashcards.md).
Selection menu	Add / remove / reorder the AI actions shown when you select text.

🇨🇳 中文（配置）：在「设置 → Lingo Studio」中可设置 LLM 的 API Key / API Base / 模型、Ask 系统提示词、词典来源（在线或 LLM 回退）、聊天与闪卡保存目录，以及选中文字时弹出的 AI 动作菜单（可增删、排序）。

---

Privacy & your data

• No secrets in this repo. The codebase ships empty/default placeholders only. Your real API key lives in the vault's plugin data.json, which is never part of this project.
• Direct, CORS-safe calls. LLM requests are made from Obsidian straight to your endpoint via requestUrl — there is no middle server and no relay.
• No telemetry. The plugin does not phone home or collect usage data.
• Local files. Chat logs and flashcards are plain Markdown files inside your vault, fully under your control.

🇨🇳 中文（隐私）：本仓库不含任何密钥，代码里只有空占位符；你的真实 API Key 只存在 vault 的插件 data.json 中，不会进入仓库。LLM 请求由 Obsidian 直接发往你的接口（经 requestUrl，无中间服务器），插件无任何遥测/上报。聊天记录与闪卡都是 vault 内的 Markdown 文件，完全由你掌控。

---

FAQ / 常见问题

Q: The panel or ribbon icon doesn't show up.

A: Enable the plugin in Settings → Community plugins, then reload Obsidian (Cmd/Ctrl + R). Also confirm the folder is named exactly lingo-studio.

🇨🇳 中文：在「设置 → 社区插件」中启用本插件，然后重载 Obsidian（Cmd/Ctrl+R）。并确认插件文件夹名严格为 lingo-studio。

Q: Dictionary shows nothing / "no definition".

A: Check spelling, and make sure Obsidian can reach api.dictionaryapi.dev (no key needed). The LLM fallback only triggers if you have set an API key and switched the source to LLM.

🇨🇳 中文：先检查拼写；确认 Obsidian 能访问 api.dictionaryapi.dev（无需密钥）。LLM 回退只在你已配置 API Key 且来源设为 LLM 时才会生效。

Q: Chat says "请设置大模型（API Key）".

A: You haven't set a key. Open Settings → Lingo Studio → LLM (Ask AI) and paste your key. Never put the key in a file or commit it.

🇨🇳 中文：说明还没填密钥。到「设置 → Lingo Studio → LLM (Ask AI)」粘贴你的 Key。不要把密钥写进文件或提交到仓库。

Q: Chat returns "LLM error 401" (or another 4xx).

A: Usually a wrong API base or model, or an invalid key. For DeepSeek use base https://api.deepseek.com/v1 and model deepseek-chat. Double-check the key is active.

🇨🇳 中文：通常是 API Base / 模型填错，或密钥无效。用 DeepSeek 时 Base 填 https://api.deepseek.com/v1、模型填 deepseek-chat。

Q: Chat returns "LLM error 5xx".

A: That's on the provider side — check your quota / billing and the provider's status page, then retry.

🇨🇳 中文：这是接口服务端的问题，检查额度/账单与厂商状态页后重试。

Q: The selection "Ask / Explain / …" menu doesn't appear.

A: Selection actions are scoped to notes inside the english-files/ folder (and its subfolders). Select text within a note there, and the menu shows up.

🇨🇳 中文：选中文字弹出的 AI 菜单只在 english-files/ 目录（含子目录）下的笔记中生效。在该目录的笔记里选中文字即可看到菜单。

Q: The Cards tab is empty, or shows words from a different note.

A: Cards are scoped per note. A word you add while reading note A only appears in the Cards tab when note A is the active note; switch to note B and you'll see B's words (or none). Look up a word and click ＋ Flashcard to add one; cards live in english-files/flashcard/flashcards.md. Words saved before this update (without a note tag) still show on every note, so your existing data isn't hidden.

🇨🇳 中文：Cards 按当前笔记隔离。在 A 笔记加的词只会在 A 为当前笔记时出现在 Cards 标签；切到 B 就显示 B 的词（或为空）。查词后点「＋ Flashcard」即可加卡，数据存在 english-files/flashcard/flashcards.md。本更新之前的旧词卡（无笔记标记）仍会在每个笔记都显示，已有的数据不会消失。

Q: Why does the flashcards.md note look like word chips instead of a table?

A: That's intentional. Lingo Studio post-processes the flashcards note and renders its words as the same clickable chips you see in the Cards tab (read-only). Click a chip to look the word up in the Dictionary tab. The underlying Markdown table is unchanged, so your data is safe.

🇨🇳 中文：flashcards.md 被渲染成和 Cards 标签一样的可点击词块（只读），这是有意设计的——点词块即可在词典查词。底层的 Markdown 表格并未改动，数据安全。

Q: The readability numbers look wrong / stale.

A: They now auto-recalculate when you switch notes. If you edited the note and want an immediate refresh, click the ↻ button in the header.

🇨🇳 中文：可读性数值会在你切换笔记时自动重算；如果刚改过正文想立即刷新，点顶部 ↻ 按钮即可。

Q: It doesn't work on mobile.

A: The plugin is desktop-only (isDesktopOnly: true) because it uses requestUrl and local files. Use it on macOS / Windows / Linux.

🇨🇳 中文：本插件仅支持桌面端（isDesktopOnly: true），使用 requestUrl 与本地文件，移动端不可用。

Q: I edited the source but nothing changed.

A: Run npm run build, then reload Obsidian (Cmd/Ctrl + R). Obsidian only reloads the plugin on a full reload.

🇨🇳 中文：先 npm run build，再重载 Obsidian（Cmd/Ctrl+R）。Obsidian 只在完整重载时才重新加载插件。

---

License

MIT © Andy. Free to use, modify, and redistribute.

🇨🇳 中文（许可）：基于 MIT 协议，可自由使用、修改与再分发。