Skip to content
BranchesTags

Repository files navigation

BlockLingo icon

BlockLingo

Streaming bilingual Minecraft chat on your trusted LAN.

CI and Release

English · 简体中文

English

BlockLingo is a client-side Fabric mod for Minecraft: Java Edition 26.2. It starts an authenticated LAN WebUI alongside the game, mirrors Minecraft chat in a bilingual interface, and streams translations from any OpenAI-compatible Chat Completions endpoint you choose.

Important

BlockLingo is client-only. It does not need to be installed on the Minecraft server. Its WebUI uses plain HTTP and is intended only for a trusted local network.

Features

  • Shows player chat and non-action-bar game messages in the WebUI, preserving the original text while the translation streams in.
  • Provides three explicit modes: LAN remote chat only with no model traffic, translate received messages only, or translate both received and sent messages.
  • In translation modes, converts received messages into your reading language and, in bidirectional mode, translates ordinary outgoing chat from Minecraft or the WebUI before sending it.
  • Commands always bypass translation, and any direction not selected for translation passes through unchanged.
  • Supports a complete custom /chat/completions URL, a model name, and an optional Bearer API key.
  • Discovers models from a compatible /models endpoint while always allowing manual model entry.
  • Keeps up to 300 recent bilingual messages in local history and restores them after a page refresh.
  • Works from phones, tablets, and computers on the same LAN through a token-protected WebUI.
  • Switches the complete WebUI between English and Simplified Chinese without reloading. The browser remembers this interface preference separately from chat translation languages.
  • Keeps provider, server, and access-token settings plus model discovery and connection tests on the computer running the mod. Authenticated LAN devices can change only the translation mode and language route.

Requirements

Component Version
Minecraft 26.2
Java 25
Fabric Loader 0.19.3 or newer
Fabric API 0.155.2+26.2
Gradle Wrapper 9.5.1
Fabric Loom 1.17.16
Bundled Node.js 24.18.0
Bundled pnpm 11.15.1
React / ReactDOM 19.2.7
Vite 8.1.5
Vitest 4.1.10

Build

Use JDK 25:

./gradlew build

Gradle downloads the pinned Node.js and pnpm versions, installs the locked React and TypeScript dependencies, type-checks the component source, runs the Vitest suite, and builds the production WebUI with Vite before packaging it in the mod JAR. A system-wide Node.js installation is not required.

For focused WebUI work:

./gradlew typecheckWeb
./gradlew testWeb
./gradlew buildWeb

The React and TypeScript source lives in src/client/web/. Components use PascalCase while hooks, functions, variables, and non-component modules use camelCase. Generated browser code is written to build/generated/clientWeb/; do not edit the generated app.js.

Local WebUI preview

You can work on the complete WebUI without starting Minecraft. With the pinned Node.js dependencies installed, run:

pnpm dev:web

Open http://127.0.0.1:4173/ for the host-device experience. The Vite development server provides React Fast Refresh, mock Bootstrap/settings/model APIs, and mock streaming translations over SSE. Use http://127.0.0.1:4173/?mode=lan to check the restricted LAN settings experience, where the translation mode and language route remain editable.

To inject a newly received message while checking the three modes, send a JSON POST to the preview-only http://127.0.0.1:4173/__preview/incoming endpoint with text and an optional sender. The message passes through unchanged in LAN remote chat mode and streams a mock translation in either translation mode.

The preview binds only to loopback by default, uses seeded fake data, and never reads Minecraft configuration, access tokens, or provider API keys. It is development tooling only and is not included in the mod JAR. Set BLOCKLINGO_PREVIEW_PORT to use a different local port.

To opt into LAN access for the preview:

BLOCKLINGO_PREVIEW_HOST=0.0.0.0 pnpm dev:web

The command prints the usable LAN URLs. Non-loopback clients are always forced into the restricted LAN experience, even if they request ?mode=local; provider and access management remain available only through 127.0.0.1.

CI and releases

.github/workflows/release.yml runs the complete Gradle build for pull requests and every push to main. On main, it creates v<mod_version> and publishes the runtime JAR when that release does not already exist. Bump mod_version in gradle.properties before publishing a new version; later commits with the same version continue to run CI without replacing an existing release.

Install

  1. Install Fabric Loader and Fabric API for Minecraft 26.2.
  2. Drop the BlockLingo runtime JAR from the latest release into the client instance's mods directory. When building from source, the JAR is written to build/libs/.
  3. Start Minecraft. No server-side installation is required.

The packaged icon is declared in fabric.mod.json and appears in compatible mod-list interfaces such as Mod Menu.

First-time setup

  1. Start Minecraft and join a world or server. BlockLingo exposes the local WebUI at http://localhost:8765/ by default.
  2. Open that address on the computer running the mod. A loopback visit pairs automatically.
  3. Open Tuning Settings and select one of the three translation modes.
  4. For either mode that translates received messages, enter a complete Chat Completions URL, add an API key only if required, and fetch or enter a model ID. Then choose your reading language and, for bidirectional translation, the outgoing target language.
  5. Test the model connection and save the settings.
  6. Use Copy Pairing Address to obtain the token-bearing LAN URL, then open it on another device on the same trusted network.

A valid endpoint is the complete URL that accepts the POST request:

https://api.example.com/v1/chat/completions

BlockLingo sends stream: true and reads standard data: {...} / data: [DONE] events. A one-shot Chat Completions JSON response is also accepted as a compatibility fallback.

Model discovery is derived only from an endpoint ending in /chat/completions; BlockLingo replaces that suffix with /models and reads standard data[].id entries. Providers without a models endpoint remain usable through manual model entry.

Without a configured model, received-message translation remains inactive. Browser-originated chat is still available in LAN remote chat and received-only modes; bidirectional mode blocks WebUI sending until translation is configured. Minecraft chat always falls back to the original message instead of being blocked.

Local data and security

BlockLingo stores configuration and history only on the computer running the mod:

  • .minecraft/config/blocklingo.json contains the translation mode, endpoint, model, API key, languages, bind address, port, and access token.
  • .minecraft/config/blocklingo-history.json contains up to 300 recent bilingual chat records.

On POSIX file systems, BlockLingo makes a best-effort attempt to restrict both files to the current user. Raw API keys and access tokens are never returned through public settings, Bootstrap, SSE, ordinary JSON responses, or logs.

The access token cannot be disabled. Rotating it disconnects existing event streams. Because the WebUI uses plain HTTP, do not forward its port or expose it directly to the public internet. Chat text is sent to the model provider you configure, so review that provider's privacy policy before use.

LAN remote chat mode sends no chat to the model provider. Received-only mode sends only received Minecraft messages; outgoing messages stay local to BlockLingo and Minecraft until they are sent unchanged to the game server.

License

MIT

简体中文

BlockLingo 是面向 Minecraft: Java Edition 26.2 的纯客户端 Fabric Mod。它随游戏启动一个带访问口令的局域网 WebUI，把 Minecraft 聊天同步到双语界面，并通过你选择的 OpenAI Chat Completions 兼容端点流式翻译消息。

Important

BlockLingo 只需安装在客户端，Minecraft 服务器无需安装。WebUI 使用明文 HTTP，仅适用于可信的本地网络。

功能

  • 在 WebUI 中显示玩家聊天和非动作栏游戏消息，始终保留原文，并流式补全译文。
  • 提供三种明确模式：完全不调用模型的局域网远程聊天、只翻译收到的消息，以及接收与发送都翻译。
  • 在翻译模式下，将收到的消息转换为阅读语言；双向翻译模式还会在发出前翻译来自 Minecraft 聊天框或 WebUI 的普通聊天。
  • 命令始终绕过翻译；未选择翻译的方向都会保持原文直发。
  • 支持完整的自定义 /chat/completions URL、模型名称和可选的 Bearer API 密钥。
  • 可从兼容的 /models 接口获取模型列表，同时始终允许手动输入模型 ID。
  • 在本地保存最多 300 条最近双语消息，页面刷新后可恢复。
  • 同一局域网中的手机、平板和电脑可通过带口令的 WebUI 使用。
  • WebUI 全站文案可在英语与简体中文间即时切换，无需刷新；浏览器会单独记住界面语言，不影响聊天翻译语言。
  • 模型服务、WebUI 服务和访问口令设置，以及模型发现和连接测试，仅允许在运行 Mod 的电脑上进行；通过口令认证的局域网设备只能修改翻译模式和语言路线。

环境要求

组件 版本
Minecraft 26.2
Java 25
Fabric Loader 0.19.3 或更高版本
Fabric API 0.155.2+26.2
Gradle Wrapper 9.5.1
Fabric Loom 1.17.16
内置 Node.js 24.18.0
内置 pnpm 11.15.1
React / ReactDOM 19.2.7
Vite 8.1.5
Vitest 4.1.10

构建

使用 JDK 25：

./gradlew build

Gradle 会下载固定版本的 Node.js 与 pnpm、安装锁定的 React 和 TypeScript 依赖、检查组件源码、运行 Vitest 测试，再由 Vite 构建 production WebUI 并打包进 Mod JAR；无需在系统中预先安装 Node.js。

只检查或构建 WebUI 时：

./gradlew typecheckWeb
./gradlew testWeb
./gradlew buildWeb

React 与 TypeScript 源码位于 src/client/web/。组件使用 PascalCase，Hook、函数、变量和非组件模块使用 camelCase。浏览器产物写入 build/generated/clientWeb/，不要直接编辑生成的 app.js。

本地预览 WebUI

无需启动 Minecraft 即可调试完整 WebUI。安装锁定的 Node.js 依赖后运行：

pnpm dev:web

打开 http://127.0.0.1:4173/ 可预览本机管理体验。Vite 开发服务器提供 React Fast Refresh、模拟的 Bootstrap、设置和模型 API，并通过 SSE 流式发送模拟译文。使用 http://127.0.0.1:4173/?mode=lan 可以检查受限的局域网设置体验，其中翻译模式和语言路线仍可修改。

检查三种模式时，可向仅供预览使用的 http://127.0.0.1:4173/__preview/incoming 发送 JSON POST，其中包含 text 和可选的 sender，以注入一条新收到的消息。纯远程聊天模式会原文直通，另两种模式会流式生成模拟译文。

预览服务默认只监听 loopback，使用预置假数据，不会读取 Minecraft 配置、访问口令或模型服务 API key。它仅用于开发，不会打进 Mod JAR。可通过 BLOCKLINGO_PREVIEW_PORT 更换本地端口。

需要显式开启局域网预览时运行：

BLOCKLINGO_PREVIEW_HOST=0.0.0.0 pnpm dev:web

命令会输出可用的局域网地址。所有非 loopback 客户端都会被强制设为受限的局域网模式，即使手动访问 ?mode=local 也无法进入完整管理界面；模型服务和访问设置仍只能通过 127.0.0.1 修改。

CI 与自动发版

.github/workflows/release.yml 会为 Pull Request 和每次推送到 main 的提交运行完整 Gradle 构建。main 中尚不存在对应 Release 时，流程会自动创建 v<mod_version> 并发布运行时 JAR。发布新版本前请先修改 gradle.properties 中的 mod_version；相同版本的后续提交仍会运行 CI，但不会覆盖已经存在的 Release。

安装

  1. 为 Minecraft 26.2 安装 Fabric Loader 和 Fabric API。
  2. 从 最新 Release 下载 BlockLingo 运行时 JAR，放入客户端实例的 mods 目录。从源码构建时产物会写入 build/libs/。
  3. 启动 Minecraft；服务器端无需安装。

图标已通过 fabric.mod.json 打包配置，会显示在 Mod Menu 等兼容的 Mod 列表界面中。

首次设置

  1. 启动 Minecraft 并进入世界或服务器。BlockLingo 默认在 http://localhost:8765/ 提供本机 WebUI。
  2. 在运行 Mod 的电脑上打开该地址；loopback 访问会自动完成配对。
  3. 打开调谐设置，选择三种翻译模式之一。
  4. 如果所选模式会翻译收到的消息，请填写完整的 Chat Completions URL，仅在服务要求时填写 API 密钥，并获取或手动填写模型 ID；随后选择阅读语言，双向翻译模式还需选择发出目标语言。
  5. 测试模型连接，成功后保存设置。
  6. 使用复制配对地址取得带口令的局域网 URL，再从同一可信网络中的其他设备打开。

端点必须是可直接接收 POST 请求的完整地址：

https://api.example.com/v1/chat/completions

BlockLingo 会发送 stream: true，并读取标准 data: {...} / data: [DONE] 事件。兼容端点若返回一次性 Chat Completions JSON，也能作为回退读取。

模型发现只会从以 /chat/completions 结尾的端点推导：BlockLingo 将该后缀替换为 /models，并读取标准 data[].id。没有模型列表接口的服务仍可通过手动输入模型 ID 使用。

模型尚未配置时，收到消息的翻译不会启用。纯远程聊天和仅接收翻译模式仍可从 WebUI 原文发言；双向翻译模式会在翻译配置完成前阻止 WebUI 发言。Minecraft 聊天始终回退为原文发送，不会被翻译配置阻断。

本地数据与安全

BlockLingo 只在运行 Mod 的电脑上保存配置和历史：

  • .minecraft/config/blocklingo.json：翻译模式、端点、模型、API 密钥、语言、监听地址、端口和访问口令。
  • .minecraft/config/blocklingo-history.json：最多 300 条最近双语聊天记录。

在 POSIX 文件系统上，BlockLingo 会尽力把两个文件限制为仅当前用户可读写。原始 API 密钥和访问口令不会通过公开设置、Bootstrap、SSE、普通 JSON 响应或日志返回。

访问口令不能关闭。轮换口令会断开现有事件流。由于 WebUI 使用明文 HTTP，请勿进行公网端口转发，也不要直接暴露到互联网。聊天原文会发送给你配置的模型服务，使用前请查看该服务的隐私政策。

纯远程聊天模式不会向模型服务发送任何聊天。仅接收翻译模式只会提交收到的 Minecraft 消息；发出消息在 BlockLingo 与 Minecraft 中保持原文，随后原样发送到游戏服务器。

许可证

MIT

About

Client-side Fabric mod for streaming bilingual Minecraft chat through an authenticated LAN WebUI.

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages