Skip to content

Albertaworlds/japanese-text-cleaner

BranchesTags

Repository files navigation

Japanese Text Cleaner

日语文本清洗工具 · 日本語テキストクリーニングツール

Automated Japanese text cleaning web application with 16-step pipeline,
batch processing, encoding auto-detection, and Agent-ready API.

Unicode正規化・全角半角変換・句点統一など16種類のクリーニングルールを搭載した、
日本語テキスト自動整形Webアプリケーション。

Next.js React TypeScript License: MIT

中文文档 · English · 日本語

🇨🇳 中文文档

功能亮点

功能 说明
16 步 Pipeline 引擎 Unicode 正规化 → 全角半角 → 片假名 → 引号状态机 → 括号 → 标点 → 单句成行 → 空行处理等，严格有序执行
三种清洗模式 深度清洗（专业文本分析）/ 标准清洗（通用文本处理）/ 轻量清洗（日常阅览优化）
批量文件处理 拖放上传多个 TXT 文件，一键批量清洗，JSZip 压缩打包导出
编码自动检测 自动识别 UTF-8 / ShiftJIS / EUC-JP，也支持手动指定
Agent API POST /api/v1/clean 固定深度清洗，可集成至 spaCy 等自然语言处理工具链
API Key 鉴权 Bearer Token / Query Parameter 两种方式，未配置密钥时自动关闭

快速开始

前置要求：Node.js 20+、pnpm 9+

git clone https://github.com/<your-username>/japanese-text-cleaner.git
cd japanese-text-cleaner
pnpm install
pnpm dev

开发服务启动后访问 http://localhost:5000。

生产构建：

pnpm build
pnpm start

环境变量

cp .env.example .env.local
变量 说明 默认值
CLEAN_API_KEY v1 API 鉴权密钥，留空关闭鉴权 (空)
PORT 服务端口 5000
COZE_PROJECT_ENV 运行环境 DEV / PROD DEV

项目结构

docs/                                # 项目文档
  skill-japanese-text-cleaner.md       # 通用设计 Skill
scripts/                             # 构建/启动脚本
src/
  app/
    api/
      clean/route.ts                   # 前端清洗 API（支持自定义选项）
      v1/clean/route.ts                # Agent API（固定深度清洗）
    layout.tsx
    page.tsx                           # 主页面
    globals.css
  components/ui/                      # shadcn/ui 组件库
  hooks/
    use-japanese-cleaner.ts            # 清洗逻辑 Hook（状态管理/文件/编码）
    use-mobile.ts
  lib/
    japanese-cleaner.ts                # 核心清洗引擎（纯函数，零外部依赖）
    utils.ts
  server.ts                            # 自定义服务器入口

清洗引擎 Pipeline

src/lib/japanese-cleaner.ts — 纯函数设计，零外部依赖，可独立打包。

cleanJapaneseText(input: string, options: CleanOptions): CleanResult
步骤 规则 关键算法
1 Unicode 正规化 (NFKC) —
2 HTML 标签移除 正则替换
3 全角 → 半角（英数字） Unicode 范围映射
4 半角片假名 → 全角 Unicode 范围映射
5 换行符统一 (CRLF→LF) 字符替换
6 分隔线块删除 有限状态机
7 控制字符移除 Unicode 类别过滤
8 引号规范化 状态机 — ASCII " → 「」 配对
9 括号规范化 半角 → 全角映射
10 标点规范化 映射表
11 行首尾空白去除 逐行 trim
12 非日文括号内容删除 栈式解析（支持嵌套）
13 长音符号统一 字符替换
14 连续空格合并 正则合并
15 单句成行 两阶段算法（合并 + 断行）
16 空行处理 合并多余 / 删除全部
三种清洗模式配置对照
规则 深度清洗 标准清洗 轻量清洗
Unicode 正规化 (NFKC) ✓ ✓ ✓
全角 → 半角 ✓ ✓ ✓
半角片假名 → 全角 ✓ ✓ ✓
空格规范化 ✓ ✓ ✓
换行符统一 ✓ ✓ ✓
控制字符移除 ✓ ✓ ✓
零宽字符移除 ✓ ✓ ✓
行首尾空白去除 ✓ ✓ ✓
移除多余空行 — ✓ —
移除所有空行 ✓ — —
引号规范化 ✓ ✓ ✓
括号规范化 ✓ ✓ ✓
HTML 标签移除 ✓ ✓ ✓
标点规范化 ✓ ✓ ✓
长音符号统一 ✓ ✓ ✓
括号内容删除 ✓ ✓ —
单句成行 ✓ — —
分隔线块删除 ✓ — —

API 文档

请求

POST /api/v1/clean
Content-Type: application/json

认证

方式 格式
Header Authorization: Bearer <api_key>
Query ?api_key=<api_key>

未配置 CLEAN_API_KEY 时鉴权自动关闭

请求体

方式一 — 纯文本

{ "text": "吾輩は猫である。名前はまだ無い。" }

方式二 — 文件 base64（自动检测编码）

{
  "file_base64": "5q2j5bi444Gv...",
  "source_encoding": "auto"
}

source_encoding 可选值：auto（默认） / utf-8 / shift_jis / euc-jp

方式三 — 批量模式

{
  "items": [
    { "text": "第一段" },
    { "file_base64": "...", "source_encoding": "shift_jis" },
    { "text": "第三段" }
  ]
}

最多 100 条。

响应体

{
  "success": true,
  "data": {
    "cleaned": "吾輩は猫である。\n名前はまだ無い。",
    "stats": {
      "originalLength": 16,
      "cleanedLength": 17,
      "removedChars": -1,
      "appliedRules": ["Unicode正规化 (NFKC)", "单句成行"]
    },
    "detectedEncoding": "utf-8 (direct)"
  }
}

错误码

code 说明
EMPTY_TEXT 文本为空
MISSING_INPUT 未提供 text 或 file_base64
INVALID_BASE64 base64 解码失败
EMPTY_ITEMS items 数组为空
TOO_MANY_ITEMS 超过 100 条
AUTH_FAILED API Key 无效
INTERNAL_ERROR 服务内部错误

Python 调用示例

import requests

API_URL = "http://localhost:5000/api/v1/clean"
API_KEY = "your-api-key"

def clean_text(raw_text: str) -> str:
    response = requests.post(
        API_URL,
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Bearer {API_KEY}",
        },
        json={"text": raw_text},
        timeout=30,
    )
    result = response.json()
    if result.get("success"):
        return result["data"]["cleaned"]
    raise Exception(f"清洗失败: {result.get('error')}")

🇬🇧 English

Highlights

Feature Description
16-step Pipeline Engine Unicode normalization → full/half-width → katakana → quote state machine → brackets → punctuation → sentence-per-line → blank line handling, executed in strict order
3 Cleaning Modes Deep (professional text analysis) / Standard (general processing) / Light (casual reading)
Batch File Processing Drag-and-drop upload, one-click batch clean, JSZip export
Auto Encoding Detection UTF-8 / ShiftJIS / EUC-JP with manual override
Agent API POST /api/v1/clean with fixed deep-cleaning mode, integrates with spaCy and other NLP pipelines
API Key Auth Bearer Token / Query Parameter, auto-disabled when no key is configured

Getting Started

Prerequisites: Node.js 20+, pnpm 9+

git clone https://github.com/<your-username>/japanese-text-cleaner.git
cd japanese-text-cleaner
pnpm install
pnpm dev

The dev server starts at http://localhost:5000.

Production build:

pnpm build
pnpm start

Environment Variables

cp .env.example .env.local
Variable Description Default
CLEAN_API_KEY API authentication key (empty = no auth) (empty)
PORT Server port 5000
COZE_PROJECT_ENV Runtime environment DEV / PROD DEV

Cleaning Engine Pipeline

src/lib/japanese-cleaner.ts — Pure function, zero dependencies, independently packagable.

cleanJapaneseText(input: string, options: CleanOptions): CleanResult
Step Rule Algorithm
1 Unicode Normalization (NFKC) —
2 HTML Tag Removal Regex
3 Full-width → Half-width (alphanumeric) Unicode range mapping
4 Half-width Katakana → Full-width Unicode range mapping
5 Line Break Unification (CRLF→LF) Char replacement
6 Separator Block Removal Finite state machine
7 Control Character Removal Unicode category filter
8 Quote Normalization State machine — ASCII " → 「」 pairing
9 Bracket Normalization Half-width → Full-width mapping
10 Punctuation Normalization Mapping table
11 Line Trimming Per-line trim
12 Non-Japanese Bracket Content Removal Stack parser (nested)
13 Long Vowel Unification Char replacement
14 Space Collapsing Regex merge
15 Sentence Per Line Two-phase algorithm (merge + break)
16 Blank Line Handling Merge extra / Remove all
Cleaning Mode Comparison
Rule Deep Standard Light
Unicode Normalization (NFKC) ✓ ✓ ✓
Full-width → Half-width ✓ ✓ ✓
Half-width Katakana → Full-width ✓ ✓ ✓
Space Normalization ✓ ✓ ✓
Line Break Unification ✓ ✓ ✓
Control Character Removal ✓ ✓ ✓
Zero-width Character Removal ✓ ✓ ✓
Line Trimming ✓ ✓ ✓
Remove Extra Blank Lines — ✓ —
Remove All Blank Lines ✓ — —
Quote Normalization ✓ ✓ ✓
Bracket Normalization ✓ ✓ ✓
HTML Tag Removal ✓ ✓ ✓
Punctuation Normalization ✓ ✓ ✓
Long Vowel Unification ✓ ✓ ✓
Bracket Content Removal ✓ ✓ —
Sentence Per Line ✓ — —
Separator Block Removal ✓ — —

API Reference

Request

POST /api/v1/clean
Content-Type: application/json

Authentication

Method Format
Header Authorization: Bearer <api_key>
Query ?api_key=<api_key>

Auth is auto-disabled when CLEAN_API_KEY is not configured.

Request Body

Mode 1 — Plain text

{ "text": "吾輩は猫である。名前はまだ無い。" }

Mode 2 — File base64 (auto-detect encoding)

{
  "file_base64": "5q2j5bi444Gv...",
  "source_encoding": "auto"
}

source_encoding options: auto (default) / utf-8 / shift_jis / euc-jp

Mode 3 — Batch

{
  "items": [
    { "text": "First text" },
    { "file_base64": "...", "source_encoding": "shift_jis" },
    { "text": "Third text" }
  ]
}

Maximum 100 items per request.

Response

{
  "success": true,
  "data": {
    "cleaned": "吾輩は猫である。\n名前はまだ無い。",
    "stats": {
      "originalLength": 16,
      "cleanedLength": 17,
      "removedChars": -1,
      "appliedRules": ["Unicode Normalization (NFKC)", "Sentence Per Line"]
    },
    "detectedEncoding": "utf-8 (direct)"
  }
}

Error Codes

code Description
EMPTY_TEXT Text is empty
MISSING_INPUT Neither text nor file_base64 provided
INVALID_BASE64 Base64 decode failed
EMPTY_ITEMS Items array is empty
TOO_MANY_ITEMS Exceeds 100 items
AUTH_FAILED Invalid API Key
INTERNAL_ERROR Internal server error

Python Example

import requests

API_URL = "http://localhost:5000/api/v1/clean"
API_KEY = "your-api-key"

def clean_text(raw_text: str) -> str:
    response = requests.post(
        API_URL,
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Bearer {API_KEY}",
        },
        json={"text": raw_text},
        timeout=30,
    )
    result = response.json()
    if result.get("success"):
        return result["data"]["cleaned"]
    raise Exception(f"Cleaning failed: {result.get('error')}")

🇯🇵 日本語

概要

Unicode正規化・全角半角変換・空白正規化・句点統一など16種類のクリーニングルールを搭載した、日本語テキスト自動整形Webアプリケーション。

主な機能

機能 説明
16ステップパイプラインエンジン Unicode正規化 → 全角半角 → 片仮名 → 引用符状態機械 → 括弧 → 句点 →一文一行 → 空行処理など、厳密な順序で実行
3つのクリーニングモード ディープクリーニング（専門テキスト分析）/ スタンダード（汎用テキスト処理）/ ライト（日常閲覧最適化）
バッチファイル処理 ドラッグ＆ドロップで複数TXTファイルをアップロード、一括クリーニング、JSZipでZIPエクスポート
エンコーディング自動検出 UTF-8 / Shift_JIS / EUC-JPを自動識別、手動指定にも対応
Agent API POST /api/v1/clean 固定ディープクリーニングモード、spaCyなどのNLPツールチェーンに統合可能
API Key認証 Bearer Token / Query Parameter、未設定時は認証を自動無効化

クイックスタート

前提条件：Node.js 20+、pnpm 9+

git clone https://github.com/<your-username>/japanese-text-cleaner.git
cd japanese-text-cleaner
pnpm install
pnpm dev

開発サーバーは http://localhost:5000 で起動します。

本番ビルド：

pnpm build
pnpm start

環境変数

cp .env.example .env.local
変数 説明 デフォルト
CLEAN_API_KEY v1 API認証キー、空欄で認証無効 (空)
PORT サービスポート 5000
COZE_PROJECT_ENV 実行環境 DEV / PROD DEV

クリーニングエンジンパイプライン

src/lib/japanese-cleaner.ts — 純粋関数、外部依存ゼロ、単独パッケージ化可能。

ステップ ルール アルゴリズム
1 Unicode正規化 (NFKC) —
2 HTMLタグ削除 正規表現
3 全角 → 半角（英数字） Unicode範囲マッピング
4 半角カタカナ → 全角 Unicode範囲マッピング
5 改行コード統一 (CRLF→LF) 文字置換
6 区切り線ブロック削除 有限状態機械
7 制御文字削除 Unicodeカテゴリフィルタ
8 引用符正規化 状態機械 — ASCII " → 「」ペアリング
9 括弧正規化 半角 → 全角マッピング
10 句点正規化 マッピングテーブル
11 行頭行末空白削除 行ごとtrim
12 非日本語括弧内容削除 スタックパーサー（ネスト対応）
13 長音記号統一 文字置換
14 連続スペース統合 正規表現マージ
15 一文一行 二段階アルゴリズム（結合 + 改行）
16 空行処理 余分な空行統合 / 全空行削除

ライセンス

MIT

About

Automated Japanese text cleaning web tool with 16-step pipeline, batch processing, encoding auto-detection, and Agent-ready API | 16種類のクリーニングルールを搭載した日本語テキスト自動整形Webツール

Resources

Readme

License

MIT license
Activity

Stars

27 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages