ドキュメント — transer.io 導入ガイド・APIリファレンス

transerとは

transerは、日本語で構築されたWebサイトをサーバーサイドで多言語翻訳するためのサービスです。ページ全体のHTMLを受け取り、文脈を保ったまま翻訳済みのHTMLを返します。

利用者が自分のサーバーに導入するのは軽量なクライアントだけです。重い翻訳処理（文脈解析・Google翻訳連携・HTML再構築）はすべてtranserサーバー側で実行されます。

💡

クライアントサイドの翻訳と何が違うの？
ブラウザ側でJavaScriptを使って翻訳する方式では、Googleなどのクローラーは翻訳前の日本語しか読めないためSEO効果がありません。 transerはサーバーサイドで翻訳済みHTMLを生成するため、クローラーが各言語のコンテンツを正しくインデックスします。

提供形態

transer（Pythonパッケージ）：Nginx/Apache2配下の自前アプリ（Flask、FastAPI、Djangoなど）向け
transer-translate（WordPressプラグイン）：WordPressサイト向け

アーキテクチャ

リクエストの流れは以下のとおりです。

text

# ① ユーザーが言語ボックスで言語を選択
ブラウザ → あなたのサーバー（Nginx/Apache2）

# ② あなたのサーバーがtranser APIにHTMLを送信
あなたのサーバー → api.transer.io
  POST /translate-page
  {
    "api_key": "tsr_live_xxxxxxxx",
    "html":    "<html>...日本語のHTML全文...</html>",
    "source_lang": "ja",
    "target_lang": "en"
  }

# ③ transerが翻訳済みHTMLを返す
api.transer.io → あなたのサーバー
  { "html": "<html>...translated HTML...</html>" }

# ④ あなたのサーバーがブラウザに返す
あなたのサーバー → ブラウザ（翻訳済みページを表示）

⚠️

「翻訳プロキシ」はあなた側で実装します。
transerが提供するのはAPIクライアント（transerパッケージ）と翻訳処理（api.transer.io）です。 Nginx/Apacheのルーティング設定と言語ボックスUIはあなたのサーバーに実装してください。詳細はNginx設定例を参照してください。

Pythonパッケージ（transer）

Nginx/Apache2配下のPythonアプリ（Flask・FastAPI・Djangoなど）に導入します。

インストール

pipでGitHubから直接インストールします。PyPIには公開していません。

bash

pip install git+https://github.com/HippoGo530/transer

特定バージョンを指定する場合（推奨）：

bash

pip install git+https://github.com/HippoGo530/transer@v0.1.0

基本的な使い方

python

from transer import Translator

translator = Translator(
    api_key="tsr_live_xxxxxxxx",   # ダッシュボードで発行したAPIキー
    base_url="https://api.transer.io"  # transer APIのURL
)

# ページ全体のHTMLを翻訳（非同期）
translated_html = await translator.translate_page(
    html=original_html,
    source_lang="ja",
    target_lang="en"
)

FastAPIでの実装例

python

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from transer import Translator
import os

app = FastAPI()
translator = Translator(
    api_key=os.environ["TRANSER_API_KEY"],
    base_url="https://api.transer.io"
)

# 言語ごとのパスで受け取る例: /en/about, /zh/about
@app.get("/{lang}/{path:path}")
async def translate_proxy(lang: str, path: str, request: Request):
    # まず日本語の元ページを取得
    original_html = await fetch_original_page(path)

    # transerで翻訳
    translated = await translator.translate_page(
        html=original_html,
        source_lang="ja",
        target_lang=lang
    )
    return HTMLResponse(translated)

Nginx設定例

言語プレフィックス付きのURLパス（例：/en/、/zh/）へのリクエストを、翻訳プロキシアプリに転送します。それ以外のリクエストは元のサイトにそのまま渡します。

nginx

server {
    listen 80;
    server_name example.com;

    # 言語プレフィックス付きリクエストは翻訳プロキシへ
    # 対応言語コードを追加した場合はここに追記する
    location ~ ^/(en|zh|ko|fr|de|es|pt|it|ru|ar|th|vi|id|ms|nl|pl)/ {
        proxy_pass http://127.0.0.1:8001;  # 翻訳プロキシアプリのポート
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 60s;  # 翻訳処理に時間がかかる場合があるため長めに設定
    }

    # それ以外（日本語の元ページ）はそのまま
    location / {
        proxy_pass http://127.0.0.1:8000;
    }
}

💡

言語ボックスのJavaScript例
言語が選択されたとき、現在のパスに言語プレフィックスを付けてリダイレクトするだけです。

javascript

function switchLang(lang) {
    const current = window.location.pathname;

    // 既に言語プレフィックスがある場合は入れ替える
    const withoutPrefix = current.replace(/^\/(en|zh|ko|fr|de|es|pt|it|ru|ar|th|vi|id|ms|nl|pl)\//, '/');

    // ja（日本語）の場合はプレフィックスなしで元ページへ
    if (lang === 'ja') {
        window.location.href = withoutPrefix;
    } else {
        window.location.href = `/${lang}${withoutPrefix}`;
    }
}

WordPressプラグイン（transer-translate）

WordPressのob_start()を使ってページ全体のHTML出力を横取りし、 transer APIで翻訳してからブラウザに返します。PHPで完結するため、 Pythonパッケージは不要です。

インストール

zipファイルをダウンロード ダッシュボードのAPIキーページから transer-translate.zip をダウンロードします。
WordPressにアップロード 管理画面 → プラグイン → 新規追加 → 「プラグインのアップロード」から zip ファイルをアップロードし、有効化します。
設定画面でAPIキーを入力 管理画面 → 設定 → transer に進み、APIキーと翻訳先言語を設定します。

⚠️

管理画面・ログイン画面は翻訳対象外です。
セキュリティと動作安定性のため、/wp-admin/、ログインページ、AJAX、REST APIエンドポイント、フィード、プレビュー画面は翻訳処理をスキップします。

設定項目

設定項目	説明	例
`transer_api_key`必須	ダッシュボードで発行したAPIキー	`tsr_live_xxxxxxxx`
`transer_api_url`必須	transer APIのエンドポイントURL	`https://api.transer.io`
`transer_source_lang`任意	元の言語コード（デフォルト: `ja`）	`ja`
`transer_target_langs`必須	翻訳先言語コードのカンマ区切りリスト	`en,zh,ko`

ショートコード

投稿・固定ページに言語切り替えUIを追加します。

text

[transer_lang_switcher]

翻訳APIタグ

翻訳APIタグは、サイトの </head> に1行追加するだけでフローティング言語セレクターを設置できるJavaScriptウィジェットです。 Pythonパッケージやサーバー設定は不要で、あらゆるCMSやHTMLサイトに対応します。

サーバー側のRewrite設定と組み合わせることで、 /en/ /ko/ のような言語プレフィックス付きURLを生成し、各言語ページを検索エンジンに正しくインデックスさせるSEO対応が可能です。

💡

Module/Pluginとの違い： Module/Pluginはサーバーが翻訳済みHTMLを生成してブラウザへ返しますが、翻訳APIタグはブラウザ上でリアルタイムに翻訳を適用します。 SEO重視ならRewrite設定との組み合わせを推奨します。

scriptタグの設置

</head> の直前に以下の1行を追加してください。 lang=ja はサイトの原文言語コードです。

HTML

<script src="https://api.transer.io/js/trsNew.js?lang=ja"
        charset="utf-8"></script>
</head>

設置後、ページをリロードするとフローティング言語セレクターが表示されます。

✅

ダッシュボード → HTMLページ翻訳タグ → ドメイン管理でドメインを登録し、APIキーを取得してから設置してください。

Rewrite設定（SEO対応）

翻訳APIタグは言語を切り替えた際、URLに /en/ /ko/ などのプレフィックスを付与します（pushState）。サーバー側でこのURLを実際のページに内部転送することで、クローラーが各言語URLをインデックスできます。

⚠️

Rewrite設定はSEO対応のためのオプションです。 設定しなくてもウィジェット自体は動作しますが、言語プレフィックスURLが 404になるためSEO効果が得られません。

Apache2 / .htaccess

.htaccess

<IfModule mod_rewrite.c>
  RewriteEngine On

  # 言語プレフィックス付きURLを実パスに内部転送
  # 例: /en/products/ → /products/（URLバーはそのまま）
  RewriteCond %{REQUEST_URI} ^/(en|ko|es|zh-CN|zh-TW)/
  RewriteRule ^(en|ko|es|zh-CN|zh-TW)/(.*)$ /$2 [L,QSA]

</IfModule>

Nginx

nginx.conf

server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    # 言語プレフィックス付きURLを実パスに内部転送
    location ~ ^/(en|ko|es|zh-CN|zh-TW)(/.*)?$ {
        try_files $2 $2/ /index.php?$query_string;
    }

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
}

WordPress (.htaccess)

WordPressの .htaccess には標準ルールが自動生成されます。 transer.io のルールはその直前に記述してください。

.htaccess — WordPress

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /

  # ── transer.io 仮想URL（WordPressルールより前に記述）──
  RewriteCond %{REQUEST_URI} ^/(en|ko|es|zh-CN|zh-TW)/
  RewriteRule ^(en|ko|es|zh-CN|zh-TW)/(.*)$ /$2 [L,QSA]

  # ── WordPress 標準ルール ──────────────────────────────
  RewriteRule ^index\.php$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.php [L]

</IfModule>

⚠️

WordPressの パーマリンク設定を保存するたびに .htaccess が再生成され、transer.io のルールが消えます。保存後は再追記してください。

動作イメージ

リクエストフロー

# ① ユーザーが英語版URLにアクセス
ブラウザ:  https://example.com/en/products/?id=23

# ② Rewriteが内部転送（URLバーは変わらない）
サーバー:  /products/?id=23 を処理

# ③ 翻訳APIタグが /en/ を検知して英語翻訳を適用
翻訳APIタグ: sessionStorage に cur_lang='en' をセット → 英語翻訳適用

# ④ URLバーをそのまま維持（pushState）
URLバー:   https://example.com/en/products/?id=23 を維持

設定オプション

scriptタグのクエリパラメータで動作をカスタマイズできます。

パラメータ	説明	デフォルト
`lang`必須	サイトの原文言語コード	`ja`
`position`任意	ウィジェットの初期表示位置。`bottom-right` / `bottom-left` / `top-right` / `top-left`	`bottom-right`
`color`任意	ウィジェットのアクセントカラー（16進カラーコード）	`#2563EB`
`exclude`任意	翻訳対象外にするCSSセレクタ（カンマ区切り）	—

カスタマイズ例

HTML

<!-- 左下に配置・オレンジ色・.no-translate クラスを除外 -->
<script
  src="https://api.transer.io/js/trsNew.js?lang=ja&position=bottom-left&color=%23F97316&exclude=.no-translate"
  charset="utf-8"></script>
</head>

💡

ウィジェットの詳細な外観設定（ロゴ・テキスト・配色）はダッシュボードの ウィジェット設定 ページでGUIから変更できます。

APIリファレンス

エンドポイントとベースURL

text

https://api.transer.io

認証

すべてのリクエストにAPIキーを含める必要があります。リクエストボディのJSONに api_key フィールドとして含めてください。

bash

curl -X POST https://api.transer.io/translate-page \
  -H "Content-Type: application/json" \
  -d '{"api_key": "tsr_live_xxxxxxxx", ...}'

POST /translate-page

HTML全体を受け取り、翻訳済みHTMLを返します。メインのエンドポイントです。

リクエストボディ

フィールド	型	説明
`api_key`必須	string	APIキー
`html`必須	string	翻訳するHTMLの全文
`source_lang`必須	string	元の言語コード（例: `ja`）
`target_lang`必須	string	翻訳先言語コード（例: `en`）

レスポンス

json

{
  "html": "<html>...翻訳済みHTML...</html>",
  "chars_translated": 1240  // 課金対象の翻訳文字数
}

💡

課金対象文字数について
曜日・年月日・元号などの決定的変換（パターンマッチで確実に変換できるもの）はGoogle翻訳APIに送信しないため、chars_translated の値が入力文字数より少なくなることがあります。課金はこの値を基準に行います。

POST /translate

テキスト配列を翻訳します。/translate-page との違いは、HTMLではなく文字列の配列を受け取る点です。下位互換のために残しています。

フィールド	型	説明
`api_key`必須	string	APIキー
`texts`必須	string[]	翻訳するテキストの配列
`source_lang`必須	string	元の言語コード
`target_lang`必須	string	翻訳先言語コード

GET /usage

APIキーごとの当月使用量（翻訳文字数・リクエスト数）を返します。

bash

curl "https://api.transer.io/usage?api_key=tsr_live_xxxxxxxx"

json

{
  "summary": [
    {
      "api_key_id": 1,
      "total_chars": 1240382,
      "request_count": 8214
    }
  ]
}

GET /health

サービスの稼働状態を確認します。監視ツールのヘルスチェックに使用してください。

bash

curl https://api.transer.io/health
# → {"status": "ok"}

対応言語一覧

120以上の言語に対応しています。以下は推奨16言語（翻訳精度を特に最適化済み）です。それ以外の言語コードはGoogle翻訳の言語コードに準拠します。

🇺🇸英語en

🇨🇳中文（簡体）zh

🇹🇼中文（繁体）zh-TW

🇰🇷한국어ko

🇫🇷Françaisfr

🇩🇪Deutschde

🇪🇸Españoles

🇵🇹Portuguêspt

🇮🇹Italianoit

🇷🇺Русскийru

🇸🇦العربيةar

🇹🇭ภาษาไทยth

🇻🇳Tiếng Việtvi

🇮🇩Bahasa Indonesiaid

🇲🇾Bahasa Melayums

🇳🇱Nederlandsnl

✅

推奨16言語はハイライト表示されています。その他の言語を使用する場合はサポートまでお問い合わせください。

言語ボックスUI例

フラグ付きのセレクトボックスを設置する最小構成の例です。スタイルは自由にカスタマイズしてください。

html

<select id="lang-switcher" onchange="switchLang(this.value)">
  <option value="ja">🇯🇵 日本語</option>
  <option value="en">🇺🇸 English</option>
  <option value="zh">🇨🇳 中文</option>
  <option value="ko">🇰🇷 한국어</option>
</select>

よくある質問

transerサーバー側にはキャッシュ機能を意図的に設けていません。これは「実際に送信した文字数のみ課金する」というビジネスモデルに基づくものです。

キャッシュを使いたい場合は、あなたのサーバー側（Nginx、Redisなど）で翻訳済みHTMLをキャッシュする実装を追加してください。2回目以降のリクエストはtranserへ送信されないため、課金も発生しません。

基本的には崩れません。transerはHTMLをブロック単位で解析し、テキストノードのみを翻訳してタグ構造に書き戻す設計のため、HTMLの構造は維持されます。

ただし、<strong>、<em>などのインライン装飾タグが文の途中にある場合、文境界の認識が変わることがあります。<a>タグのhref属性はそのまま保持されます。

翻訳リクエストがタイムアウトまたはエラーになります。フォールバック処理はあなたのサーバー側で実装してください。たとえば、翻訳失敗時に日本語の元ページを返す、または「現在翻訳サービスが利用できません」と表示するなどの対応が推奨です。

はい、いつでも変更できます。変更は翌月1日から適用されます。月の途中でアップグレードが必要な場合はサポートまでご連絡ください。

ダッシュボードから該当のAPIキーを即座に「失効」させてください。失効させたキーは以降のリクエストで認証エラーになります。新しいキーを発行して設定を更新してください。

APIキーはサーバーの環境変数に設定し、ソースコードやGitリポジトリに直接記述しないようにしてください。