jtcg_locale_detector 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8aabdb6f28de3e21527b5a81fa9eac577fb16f988c132f3c528a8b4b88c6c061
+  data.tar.gz: 2f017a60989427af6030b4d857dc7ceb0f772f4ce5999bda2710779ce874c859
+SHA512:
+  metadata.gz: 0a63302d720b0ddb6fc1ac6d1c162b7e948d80f47c32625a8bc20599c46c1683a0a8f63730b136f915af7999ebd0bf2610bc4c0e0ac489a14c63e88723fb265d
+  data.tar.gz: 6f6b3ea226dae8b0e37c5bfc88e758edea6ebd25a573149161b0de62e6952e1f777265503f83abd98f8616b93e801e176b87f58418a184541dde90ee6e5be1e4

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] - 2025-06-01
+
+### Added
+- Initial Ruby gem release
+- Support for 176 languages detection
+- Specialized Chinese Traditional/Simplified detection
+- Command-line interface
+- Batch processing capabilities
+- Multiple detection modes (conversion, ratio, both)
+- Multiple output formats (simple, json, detailed)
+- Low memory mode support
+- File detection support
+- Comprehensive test suite
+- RuboCop configuration
+- Documentation and examples
+
+### Features
+- FastText-based language identification
+- OpenCC-based Chinese variant detection
+- Character ratio analysis for Chinese
+- Async batch processing
+- Memory-optimized operations
+- Cross-platform compatibility (macOS, Linux, Windows)
+
+### Dependencies
+- Ruby 2.7.0+
+- Python 3.11+
+- FastText
+- OpenCC
+- zhon

data/PACKAGING_SUMMARY.md

@@ -0,0 +1,195 @@
+# LocaleDetector Ruby Gem 打包總結
+
+## 概述
+
+已成功將 LocaleDetector 語言檢測專案打包成 Ruby gem，讓 Ruby 開發者能夠輕鬆使用這個強大的多語言檢測工具。
+
+## 專案結構
+
+```
+ruby-gem/
+├── lib/                          # Ruby 源代碼
+│   ├── locale_detector.rb        # 主模組
+│   └── locale_detector/
+│       ├── version.rb            # 版本定義
+│       ├── client.rb             # 主要客戶端類
+│       └── detector.rb           # 檢測器輔助類
+├── python/                       # Python 組件
+│   ├── cli.py                    # Python CLI 腳本
+│   ├── requirements.txt          # Python 依賴
+│   └── src/                      # Python 源代碼
+├── bin/
+│   └── locale-detector           # Ruby CLI 工具
+├── spec/                         # 測試文件
+├── examples/
+│   └── basic_usage.rb            # 使用範例
+├── locale_detector.gemspec       # Gem 規格
+├── Gemfile                       # Ruby 依賴
+├── Rakefile                      # 構建任務
+├── README.md                     # 文檔
+├── CHANGELOG.md                  # 變更日誌
+├── install.sh                    # 安裝腳本
+└── build.sh                      # 構建腳本
+```
+
+## 核心特性
+
+### 1. Ruby API
+- **簡單檢測**: `LocaleDetector.detect(text)`
+- **批次檢測**: `LocaleDetector.detect_batch(texts)`  
+- **檔案檢測**: `LocaleDetector.detect_file(path)`
+- **詳細信息**: `client.detect_with_details(text)`
+
+### 2. 命令列工具
+- 支援單一文本、檔案和批次檢測
+- 多種輸出格式（simple, json, detailed）
+- 不同檢測模式（conversion, ratio, both）
+- 低記憶體模式
+
+### 3. 語言支援
+- 176 種語言檢測
+- 特別優化中文繁簡體檢測
+- 支援 zh-TW, zh-CN, zh-HK, zh-MO, zh-SG
+
+## 技術實現
+
+### 架構設計
+本 Ruby gem 採用**混合架構**，結合 Ruby 的易用性和 Python 的機器學習生態：
+
+1. **Ruby 層**: 提供友好的 API 和命令列界面
+2. **Python 層**: 執行實際的語言檢測工作
+3. **IPC 通訊**: 通過 subprocess 調用 Python CLI
+
+### 核心組件
+
+#### LocaleDetector::Client
+- 管理 Python 環境檢查
+- 處理命令構建和執行
+- 解析 Python 輸出結果
+- 錯誤處理和異常管理
+
+#### LocaleDetector::Detector  
+- 提供靜態信息（支援語言、檢測模式等）
+- 語言支援檢查
+- 中文變體識別
+
+## 安裝和使用
+
+### 系統要求
+- Ruby 2.7.0+
+- Python 3.11+
+- pip
+
+### 安裝步驟
+
+1. **安裝 gem**:
+   ```bash
+   gem install locale_detector-1.0.1.gem
+   ```
+
+2. **安裝 Python 依賴**:
+   ```bash
+   pip install -r python/requirements.txt
+   ```
+
+### 快速開始
+
+```ruby
+require 'locale_detector'
+
+# 基本檢測
+result = LocaleDetector.detect("Hello world")
+puts result["locale"]  # => "en-US"
+
+# 中文檢測
+result = LocaleDetector.detect("繁體中文")
+puts result["locale"]  # => "zh-TW"
+
+# 批次檢測
+results = LocaleDetector.detect_batch(["Hello", "你好", "こんにちは"])
+```
+
+### 命令列使用
+
+```bash
+# 基本檢測
+locale-detector "Hello world"
+
+# 從檔案檢測
+locale-detector --file input.txt
+
+# JSON 輸出
+locale-detector "測試" --output-format json
+
+# 詳細信息
+locale-detector "測試" --details
+```
+
+## 測試和品質保證
+
+### 測試套件
+- RSpec 測試框架
+- 涵蓋基本檢測、批次處理、檔案檢測
+- 錯誤處理測試
+- 配置選項測試
+
+### 代碼品質
+- RuboCop 代碼風格檢查
+- 文檔覆蓋率
+- 持續集成準備
+
+## 性能考量
+
+### 優點
+- **快速啟動**: Ruby API 響應迅速
+- **記憶體效率**: 支援低記憶體模式
+- **批次處理**: 高效處理多個文本
+
+### 限制
+- **進程開銷**: 每次檢測需啟動 Python 進程
+- **依賴複雜**: 需要 Python 環境和機器學習依賴
+
+### 最佳化建議
+- 批次處理多個文本而非單獨檢測
+- 重用 Client 實例避免重複驗證
+- 在生產環境中考慮快取策略
+
+## 部署選項
+
+### 1. 傳統部署
+- 安裝 Ruby gem
+- 確保 Python 環境可用
+- 安裝 Python 依賴
+
+### 2. 容器化部署
+- 創建包含 Ruby + Python 的 Docker 鏡像
+- 預安裝所有依賴
+- 適合微服務架構
+
+### 3. 無伺服器部署
+- 適合 AWS Lambda、Google Cloud Functions
+- 需要自定義運行時或容器
+
+## 未來改進方向
+
+### 短期改進
+1. **連接池**: 維持 Python 進程池減少啟動開銷
+2. **快取機制**: 本地快取常見檢測結果
+3. **異步支援**: Ruby async/await 支援
+
+### 長期計劃
+1. **純 Ruby 實現**: 移植核心演算法到 Ruby
+2. **C 擴展**: 編寫高效能 C 擴展
+3. **gRPC 服務**: 獨立語言檢測服務
+
+## 結論
+
+LocaleDetector Ruby gem 成功地橋接了 Ruby 和 Python 生態系統，為 Ruby 開發者提供了強大的語言檢測功能。雖然存在一些性能開銷，但通過合理的使用方式（如批次處理）可以有效緩解。
+
+這個 gem 特別適合：
+- 需要多語言支援的 Ruby 應用
+- 中文繁簡體檢測需求
+- 文檔處理和國際化項目
+- 多語言內容管理系統
+
+gem 包大小為 129MB，主要包含機器學習模型和 Python 依賴，在合理範圍內。

data/README.md

@@ -0,0 +1,226 @@
+# LocaleDetector Ruby Gem
+
+多語言地區檢測工具的Ruby綁定，特別針對中文繁簡體檢測進行優化。
+
+## 特色功能
+
+- 🌍 支援 176 種語言檢測
+- 🇨🇳 特別優化中文繁體 (zh-TW) 和簡體 (zh-CN) 檢測
+- ⚡ 高效能檢測
+- 📊 多種檢測模式和輸出格式
+- 🔧 命令列工具和 Ruby API
+- 🐍 基於成熟的Python語言檢測引擎
+
+## 安裝
+
+將此行添加到應用程式的 Gemfile：
+
+```ruby
+gem 'locale_detector'
+```
+
+然後執行：
+
+```bash
+$ bundle install
+```
+
+或者手動安裝：
+
+```bash
+$ gem install locale_detector
+```
+
+### 系統要求
+
+- Ruby 2.7.0 或更高版本
+- Python 3.11 或更高版本
+- pip (用於安裝 Python 依賴)
+
+### Python 依賴安裝
+
+安裝 gem 後，需要安裝 Python 依賴：
+
+```bash
+$ rake install_python_deps
+```
+
+或手動安裝：
+
+```bash
+$ pip install -r python/requirements.txt
+```
+
+## 使用方法
+
+### Ruby API
+
+#### 基本檢測
+
+```ruby
+require 'locale_detector'
+
+# 檢測單一文本
+result = LocaleDetector.detect("Hello world")
+puts result["locale"]  # => "en-US"
+
+# 檢測中文繁體
+result = LocaleDetector.detect("繁體中文測試")
+puts result["locale"]  # => "zh-TW"
+
+# 檢測中文簡體
+result = LocaleDetector.detect("简体中文测试")
+puts result["locale"]  # => "zh-CN"
+```
+
+#### 批次檢測
+
+```ruby
+texts = ["Hello world", "繁體中文", "简体中文", "Bonjour le monde"]
+results = LocaleDetector.detect_batch(texts)
+
+results.each_with_index do |result, index|
+  puts "Text #{index + 1}: #{result['locale']}"
+end
+```
+
+#### 從檔案檢測
+
+```ruby
+result = LocaleDetector.detect_file("path/to/text/file.txt")
+puts result["locale"]
+```
+
+#### 進階選項
+
+```ruby
+# 使用不同的檢測模式
+client = LocaleDetector::Client.new(
+  mode: "ratio",           # 'conversion', 'ratio', 'both'
+  low_memory: false,       # 使用低記憶體模式
+  output_format: "json"    # 'simple', 'json', 'detailed'
+)
+
+result = client.detect("測試文本")
+
+# 獲取詳細檢測信息
+detailed_result = client.detect_with_details("測試文本")
+puts detailed_result.inspect
+```
+
+### 命令列工具
+
+安裝 gem 後，您可以使用 `locale-detector` 命令：
+
+```bash
+# 檢測單一文本
+$ locale-detector "Hello world"
+en-US
+
+# 從檔案檢測
+$ locale-detector --file input.txt
+
+# 批次處理
+$ locale-detector --batch file1.txt file2.txt
+
+# 使用不同模式
+$ locale-detector "中文文本" --mode ratio --details
+
+# JSON 輸出
+$ locale-detector "測試" --output-format json
+{
+  "locale": "zh-TW"
+}
+
+# 詳細信息
+$ locale-detector "測試" --output-format detailed --details
+```
+
+### 支援的選項
+
+#### 檢測模式
+
+- `conversion`: 快速模式，使用字符轉換比較
+- `ratio`: 準確模式，使用字符比例分析（預設）
+- `both`: 混合模式，結合兩種方法
+
+#### 輸出格式
+
+- `simple`: 簡單文本輸出（預設）
+- `json`: JSON 格式輸出
+- `detailed`: 詳細信息輸出
+
+## 支援的語言
+
+本工具支援 176 種語言的檢測，包括但不限於：
+
+- 中文變體：`zh-TW` (繁體), `zh-CN` (簡體), `zh-HK`, `zh-MO`, `zh-SG`
+- 歐洲語言：`en`, `es`, `fr`, `de`, `it`, `pt`, `ru`, `nl`, `sv`, `no`, `da`
+- 亞洲語言：`ja`, `ko`, `th`, `vi`, `hi`, `ar`, `he`, `tr`
+- 其他語言：查看 `LocaleDetector::Detector.supported_languages`
+
+## API 參考
+
+### LocaleDetector
+
+#### 類方法
+
+- `LocaleDetector.detect(text, **options)` - 檢測單一文本
+- `LocaleDetector.detect_batch(texts, **options)` - 批次檢測
+- `LocaleDetector.detect_file(file_path, **options)` - 從檔案檢測
+
+### LocaleDetector::Client
+
+#### 實例方法
+
+- `#detect(text)` - 檢測單一文本
+- `#detect_batch(texts)` - 批次檢測
+- `#detect_file(file_path)` - 從檔案檢測
+- `#detect_with_details(text)` - 獲取詳細檢測信息
+
+#### 選項
+
+- `mode`: 檢測模式（'conversion', 'ratio', 'both'）
+- `low_memory`: 使用低記憶體模式
+- `output_format`: 輸出格式（'simple', 'json', 'detailed'）
+- `encoding`: 檔案編碼（預設: 'utf-8'）
+
+### LocaleDetector::Detector
+
+#### 類方法
+
+- `Detector.supported_languages` - 取得支援的語言列表
+- `Detector.chinese_variants` - 取得中文變體信息
+- `Detector.detection_modes` - 取得可用的檢測模式
+- `Detector.language_supported?(language_code)` - 檢查是否支援某語言
+- `Detector.chinese_variant?(locale)` - 檢查是否為中文變體
+
+## 開發
+
+獲取原始碼後，執行 `bin/setup` 安裝依賴。然後，執行 `rake spec` 來運行測試。您也可以執行 `bin/console` 來取得互動式提示符進行實驗。
+
+要將此 gem 安裝到本地機器，執行 `bundle exec rake install`。要發布新版本，更新 `version.rb` 中的版本號，然後執行 `bundle exec rake release`，這將創建一個 git 標籤並推送 `.gem` 檔案到 [rubygems.org](https://rubygems.org)。
+
+## 貢獻
+
+Bug 報告和 pull request 歡迎在 GitHub 上提交：https://github.com/jtcg/locale-detector
+
+## 授權
+
+## 作者與貢獻者
+
+- **原作者**: [原作者姓名](mailto:original.author@example.com) - 核心語言檢測引擎開發
+- **Ruby Gem 打包**: [JTCG Team](mailto:mark@j-tcg.com) - Ruby 綁定與 gem 打包
+- **維護者**: JTCG Team
+
+## 開源授權
+
+此 gem 可在 [MIT License](https://opensource.org/licenses/MIT) 條款下使用。
+
+## 致謝
+
+本工具基於以下開源專案：
+
+- [FastText](https://fasttext.cc/) - Facebook 的語言檢測模型
+- [OpenCC](https://github.com/BYVoid/OpenCC) - 中文繁簡轉換
+- [zhon](https://github.com/tsroten/zhon) - 中文字符數據

data/bin/locale-detector

@@ -0,0 +1,159 @@
+#!/usr/bin/env ruby
+
+require "optparse"
+require "json"
+require_relative "../lib/locale_detector"
+
+options = {
+  mode: "ratio",
+  low_memory: false,
+  output_format: "simple",
+  details: false,
+  encoding: "utf-8"
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: locale-detector [OPTIONS] TEXT"
+  opts.separator ""
+  opts.separator "多語言地區檢測工具 - 特別優化中文繁簡體檢測"
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on("-f", "--file FILE", "從檔案讀取文本進行檢測") do |file|
+    options[:file] = file
+  end
+
+  opts.on("--batch FILES", Array, "批次處理多個檔案") do |files|
+    options[:batch] = files
+  end
+
+  opts.on("--mode MODE", %w[conversion ratio both],
+          "中文檢測模式: conversion(快速), ratio(準確), both(混合) [預設: ratio]") do |mode|
+    options[:mode] = mode
+  end
+
+  opts.on("--low-memory", "使用低記憶體模式") do
+    options[:low_memory] = true
+  end
+
+  opts.on("--output-format FORMAT", %w[simple json detailed],
+          "輸出格式: simple(簡單), json(JSON格式), detailed(詳細信息) [預設: simple]") do |format|
+    options[:output_format] = format
+  end
+
+  opts.on("--details", "顯示檢測詳細信息") do
+    options[:details] = true
+  end
+
+  opts.on("--encoding ENCODING", "檔案編碼格式 [預設: utf-8]") do |encoding|
+    options[:encoding] = encoding
+  end
+
+  opts.on("-o", "--output FILE", "將結果輸出到檔案") do |output|
+    options[:output] = output
+  end
+
+  opts.on("-h", "--help", "顯示幫助信息") do
+    puts opts
+    exit
+  end
+
+  opts.on("--version", "顯示版本信息") do
+    puts "locale-detector #{LocaleDetector::VERSION}"
+    exit
+  end
+end
+
+begin
+  parser.parse!
+rescue OptionParser::InvalidOption => e
+  puts "Error: #{e.message}"
+  puts parser
+  exit 1
+end
+
+def format_output(result, format)
+  case format
+  when "json"
+    JSON.pretty_generate(result)
+  when "detailed"
+    if result.is_a?(Hash)
+      result.map { |k, v| "#{k}: #{v}" }.join("\n")
+    else
+      result.to_s
+    end
+  else
+    if result.is_a?(Hash) && result["locale"]
+      result["locale"]
+    else
+      result.to_s
+    end
+  end
+end
+
+def handle_output(content, output_file)
+  if output_file
+    File.write(output_file, content)
+    puts "結果已輸出到: #{output_file}"
+  else
+    puts content
+  end
+end
+
+begin
+  client = LocaleDetector::Client.new(
+    mode: options[:mode],
+    low_memory: options[:low_memory],
+    output_format: options[:output_format],
+    encoding: options[:encoding]
+  )
+
+  if options[:batch]
+    # 批次處理
+    results = {}
+    options[:batch].each do |file|
+      result = if options[:details]
+                 client.detect_with_details(File.read(file, encoding: options[:encoding]))
+               else
+                 client.detect_file(file)
+               end
+      results[file] = result
+    rescue StandardError => e
+      results[file] = { error: e.message }
+    end
+    output = format_output(results, options[:output_format])
+    handle_output(output, options[:output])
+
+  elsif options[:file]
+    # 從檔案檢測
+    result = if options[:details]
+               client.detect_with_details(File.read(options[:file], encoding: options[:encoding]))
+             else
+               client.detect_file(options[:file])
+             end
+    output = format_output(result, options[:output_format])
+    handle_output(output, options[:output])
+
+  elsif !ARGV.empty?
+    # 檢測命令列參數中的文本
+    text = ARGV.join(" ")
+    result = if options[:details]
+               client.detect_with_details(text)
+             else
+               client.detect(text)
+             end
+    output = format_output(result, options[:output_format])
+    handle_output(output, options[:output])
+
+  else
+    puts "Error: 請提供要檢測的文本或檔案"
+    puts parser
+    exit 1
+  end
+rescue LocaleDetector::Error => e
+  puts "Error: #{e.message}"
+  exit 1
+rescue StandardError => e
+  puts "Unexpected error: #{e.message}"
+  exit 1
+end

data/jtcg_locale_detector.gemspec

@@ -0,0 +1,48 @@
+Gem::Specification.new do |spec|
+  spec.name          = "jtcg_locale_detector"
+  spec.version       = "1.0.1"
+  
+  # 原作者（模組開發者）
+  spec.authors       = ["Original mark", "JTCG Team"]
+  spec.email         = ["mark@j-tcg.com", "enor@j-tcg.com"]
+
+  spec.summary       = "多語言地區檢測工具，特別優化中文繁簡體檢測"
+  spec.description   = "Multi-language locale detector with specialized Chinese variant detection. " \
+                       "Uses FastText for initial language identification and multiple algorithms " \
+                       "for Chinese variant detection. Ruby gem packaged by JTCG Team."
+  spec.homepage      = "https://github.com/jtcg/locale-detector"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/jtcg/locale-detector"
+  spec.metadata["changelog_uri"] = "https://github.com/jtcg/locale-detector/blob/main/CHANGELOG.md"
+  
+  # 作者角色說明
+  spec.metadata["packaged_by"] = "JTCG Team <enor@j-tcg.com>"
+  spec.metadata["original_author"] = "Original mark <mark@j-tcg.com>"
+  spec.metadata["maintainer"] = "JTCG Team"
+  spec.metadata["funding_uri"] = "https://github.com/sponsors/jtcg"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir["{bin,lib,python}/**/*", "*.md", "*.txt", "*.gemspec"]
+  end
+
+  spec.bindir        = "bin"
+  spec.executables   = ["locale-detector"]
+  spec.require_paths = ["lib"]
+
+  # Dependencies
+  spec.add_dependency "ffi", "~> 1.15"
+  spec.add_dependency "json", "~> 2.6"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", ">= 1.17"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+
+  # Metadata
+  spec.metadata["rubygems_mfa_required"] = "true"
+end