For English users: English

WOVN.io Java ライブラリは Java アプリケーションで WOVN.io ライブラリ方式の翻訳を実現するライブラリです。WOVN.io Java ライブラリは Servlet Filter として実装されています。

本ドキュメントは WOVN.io Java ライブラリのインストール手順と、設定パラメータについて説明します。

WOVN.io Java ライブラリを使用するためには、WOVN.io のアカウントが必要です。 アカウントをお持ちでない場合は、まず WOVN.io にてサインアップをしてください。

WOVN.io にサインインをして、翻訳したいページを追加してください

※ Maven 以外をお使いの場合は、こちらの設定方法をご覧ください。(https://jitpack.io/#wovnio/wovnjava)

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
    <!-- SNAPSHOT バージョンを使用しない場合は、以下の行は必要ありません。 -->
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </snapshots>
    <!-- end -->
  </repository>
</repositories>

<dependency>
  <groupId>com.github.wovnio</groupId>
  <artifactId>wovnjava</artifactId>
  <!-- 使用するライブラリのバージョンを指定してください。 -->
  <!-- 開発中のバージョンを使用する場合は、「-SNAPSHOT」 を設定してください。 -->
  <version>0.1.0</version>
</dependency>

使用可能なライブラリのバージョンはこちらのページで確認できます。(https://jitpack.io/#wovnio/wovnjava)

web.xml で、WovnServletFilterのパラメータを設定します。

4つの必須パラメータ:

1. projectToken
2. defaultLang
3. supportedLangs
4. urlPattern

これらのパラメータがあなたのWovnプロジェクトと一致していることが重要です。パラメータの詳細はセクション2に記載されています。

WovnServletFilterの最小構成の例は以下のようになります。これは、トークンが "123abc"、翻訳元が日本語、翻訳先が英語のプロジェクトの場合です。

<filter>
  <filter-name>wovn</filter-name>
  <filter-class>com.github.wovnio.wovnjava.WovnServletFilter</filter-class>
  <init-param>
    <param-name>projectToken</param-name>
    <param-value>123abc</param-value>
  </init-param>
  <init-param>
    <param-name>defaultLang</param-name>
    <param-value>ja</param-value>
  </init-param>
  <init-param>
    <param-name>supportedLangs</param-name>
    <param-value>ja,en</param-value>
  </init-param>
  <init-param>
    <param-name>urlPattern</param-name>
    <param-value>path</param-value>
  </init-param>
</filter>

<filter-mapping>
  <filter-name>wovn</filter-name>
  <!-- ライブラリ (Servlet Filter) を適用する URL パターンを設定してください。 -->
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>FORWARD</dispatcher>
</filter-mapping>

推奨される filter-mapping は、ディスパッチャに REQUEST と FORWARD を許可し、url-pattern にあるすべてのパスを許可することです。ウェブサーバ上の特定のディレクトリだけを WovnServletFilter が対象としたい場合は、それに応じて url-pattern を設定してください。

WOVN.io Java ライブラリに設定可能なパラメータは以下の通りです。

※ 初期値が設定されている必須パラメータは、web.xml で設定しなくても大丈夫です。（projectToken だけ指定すればライブラリを動作させることができます）

あなたの WOVN.io アカウントのユーザートークンを設定してください。このパラメータは必須です。

ウェブサーバのコンテンツの翻訳元の言語。

defaultLang は 2 文字の言語コードとして宣言されています。 このドキュメントの下部にある言語コードのリストを参照してください。

このプロジェクトで使用するすべての言語のリスト。(defaultLangは自動的にこのリストに含まれます)。

supportedLangs は、言語コードのカンマ区切りのリストとして宣言されています。 このドキュメントの一番下にある言語コードのリストを参照してください。

翻訳された言語のページを指すURLの形式。

WovnServletFilter は、翻訳された言語で宣言されたリクエストURLを受け入れます。 この設定は、それらのURLがどのように見えるかを指定します。

3つの基本的なURLパターンが利用可能で、高度にカスタマイズ可能なカスタムドメインオプションもあります。

以下の例は、韓国語(翻訳された言語)のページを訪問したときのオリジナルURL https://wovn.io/contact のためのものです。

URL形式 | 翻訳されたページのURL | 説明 path | https://wovn.io/ko/contact | 言語コードはパスの最初の部分に挿入されます subdomain | https://ko.wovn.io/contact | 言語コードが最初のサブドメインとして挿入されます。(このオプションにはDNS設定が設定されている必要があります) query | https://wovn.io/contact?wovn=ko | 言語コードがクエリパラメータとして挿入されます。(このオプションはアプリケーションへの変更を最小限に抑えます) customDomain | (下記2.10項参照) | カスタムドメインオプションでは、各言語のドメインとパスを独立して定義することができます。

Javaウェブサーバがリバースプロキシの後ろにある場合に設定するフラグ。

WovnServletFilter が受信したリクエストが Wovn プロジェクトにマッチするホスト名を持っていない場合、ページの翻訳データにアクセスできない可能性があります。これは、リクエストがリバースプロキシを介してルーティングされている場合に発生する可能性があります。

useProxy を true に設定すると、WovnServletFilter は HTTP リクエストヘッダ X-Forwarded-Host と X-Forwarded-Port を使用してリクエストのホスト名とポートを決定します。

次のように useProxy を true に設定します。

<init-param>
  <param-name>useProxy</param-name>
  <param-value>true</param-value>
</init-param>

リバースプロキシがリクエストパスやクエリを書き換える場合、 originalUrlHeaderやoriginalQueryStringHeaderの設定も必要になるかもしれないことに注意して下さい。

元のリクエストパスとクエリを宣言するためのHTTPヘッダの名前。

例えば、Apache HTTP Serverのmod_rewriteモジュールを使用して、着信リクエストが書き換えられている場合、WovnServletFilterは元のリクエストURLを見ることができないかもしれません。この場合、API サーバから正しい翻訳データを取得できないかもしれません。

originalUrlHeader と originalQueryStringHeader が設定されている場合、WovnServletFilter はこれらの HTTP ヘッダ名を検査して元のパスとクエリを決定します。 originalUrlHeader は元のパスの HTTP ヘッダ名を宣言しなければなりません。

これらのパラメータが設定されている場合、useProxy は true に設定されるべきです。

この例では、HTTPヘッダ名 X-Request-Uri と X-Query-String を用いてパスとクエリを宣言します。

受信したリクエストのパスとクエリを HTTP ヘッダに保存するように Apache を設定します。

SetEnvIf Request_URI "^(.*)$" REQUEST_URI=$1
RequestHeader set X-Request-Uri "%{REQUEST_URI}e"
RewriteRule .* - [E=REQUEST_QUERY_STRING:%{QUERY_STRING}]
RequestHeader set X-Query-String "%{REQUEST_QUERY_STRING}e"

WovnServletFilter を設定して、同じ HTTP ヘッダからのリクエストパスとクエリを決定します。

<init-param>
  <param-name>originalUrlHeader</param-name>
  <param-value>X-Request-Uri</param-value>
</init-param>
<init-param>
  <param-name>originalQueryStringHeader</param-name>
  <param-value>X-Query-String</param-value>
</init-param>

上記のサンプルリクエストヘッダーは、以下のサイトから参照: https://coderwall.com/p/jhkw7w/passing-request-uri-into-request-header

WOVNに翻訳をスキップさせたいHTMLクラスのカンマ区切りのリスト。 （翻訳対象のページに含まれる機密データを、WOVNへ送信しないようにするための設定です）

無視された要素とその内容はWovnServletFilterによって処理されず、翻訳のためにWovn.ioに送られません。(しかし、要素は結果としてのウェブページにはまだ存在します)。

例えば、このパラメータに my-secret-class を含め、以下のような要素を持つとします。

  <div>
    <p class="my-secret-class">Some information WOVN does not touch</p>
  </div>

翻訳の目的上、WOVNはそれを空であるかのように扱います

  <div></div>

ignoreClasses パラメータに email-address-element, my-secret-class, noshow の3つのクラスを含めると、以下のようになります。

<init-param>
  <param-name>ignoreClasses</param-name>
  <param-value>email-address-element,my-secret-class,noshow</param-value>
</init-param>

ServletResponse.flushBuffer()`の振る舞いを調整するフラグ。

このパラメータはデフォルトで false に設定されています(推奨)。

enableFlushBuffer が false に設定されている場合、WovnServletFilter はクライアントにコンテンツをすぐに書き込まずに response.flushBuffer() の呼び出しを捕捉します。 完全な HTML レスポンスの準備ができて初めて、フィルタはコンテンツを翻訳してクライアントに送信します。これは適切に翻訳するために必要なことです。

このパラメータでは、WOVN がページを翻訳する際のアンカーとして使用するプレフィックスパスを設定します。この設定では、WOVN はプレフィックスパスにマッチするページのみを翻訳し、 パスの言語コードはプレフィックスパスの後に追加されます。

例えば、以下のように sitePrefix のパスを city に設定したとします。

<init-param>
  <param-name>sitePrefixPath</param-name>
  <param-value>city</param-value>
</init-param>

WOVNはhttp://www.mysite.com/city/*にマッチするページのみを翻訳します。 http://www.mysite.com/city/tokyo/map.html が翻訳され、以下のように言語コード(英語)で、そのページにアクセスできるようになります。 http://www.mysite.com/city/en/tokyo.map.html のような言語コード(英語)でそのページにアクセスできるようになります。

デフォルトでは、WOVNはあなたのドメインのすべてのページを翻訳し、パスの言語コードをパスの最初に処理します。

この設定は urlPattern = path の設定と併用することができます。

さらに、WovnServletFilterに対応するフィルタマッピングを web.xml に設定することを強く推奨します。上の例のようにプレフィックスパスを city に設定すると、対応するフィルタマッピングは以下のようになります。

<filter-mapping>
  <filter-name>wovn</filter-name>
  <url-pattern>/city/*</url-pattern>
  ...
</filter-mapping>

この設定では、サポートされている言語の言語識別子を指定することができます。

例えば、英語のデフォルトの言語識別子は en であり、英語のページのURLは http://site.com/en/page のように見えるかもしれません。 langCodeAliases を使うと、言語識別子を例えば us に変更することができます。結果として得られるURLは http://site.com/us/page のようになります。

この設定は、URLパターン path, query, subdomain に対してのみ有効です。

形式は以下の通りです。

FORMAT: <langCode>:<alias>,<langCode>:<alias>,...

EXAMPLE: ja:japan,en:us

web.xml では、設定は以下のようになります。

<init-param>
  <param-name>langCodeAliases</param-name>
  <param-value>ja:japan,en:us</param-value>
</init-param>

元のコンテンツが既に言語コードを含む場所に存在する場合、デフォルト言語の言語エイリアスを設定することで、WovnServletFilter がこのパスやサブドメインを言語コードとして扱うようにすることができます。

説明のために、ここでは一例を示します:

あなたのコンテンツはすでに http://site.com/jp/* に存在し、デフォルトの言語は日本語です。

英語の翻訳コンテンツのURLは、 /jp/ を /en/ に変更して、 http://site.com/jp/home.html が http://site.com/en/home.html になるようにしたい。

日本語のエイリアスとして jp を設定することで、この結果を得ることができます。

この設定では、サポートされている各言語に対応するドメインとパスを定義できます。

設定の形式は以下の通りです

FORMAT: <baseURL>:<langCode>,<baseURL>:<langCode>,...

EXAMPLE: www.site.co.jp:ja,www.site.com/english:en

<baseURL> はホストとパスのプレフィックスのみを持つことに注意してください。 ホストの前には http:// のようなものを含めてはならない。ポート番号も含めてはならない。ただし、該当するサブドメインはすべて含めなければならない。

上記の例では、www.site.co.jp にマッチするリクエストURLはすべて日本語のリクエストとして扱われます。 また、www.site.com/english/* にマッチするリクエストURLはすべて英語のリクエストとして扱われます。 例えば www.site.com/admin のようにドメイン言語にマッチしないリクエストは WovnServletFilter によって処理されません。

上記の例では、英語のページ http://www.site.co.jp/about.html は http://www.site.com/english/about.html というURLを持つことになります。

対応する web.xml パラメータは以下のようになります。

<init-param>
  <param-name>urlPattern</param-name>
  <param-value>customDomain</param-value>
</init-param>
<init-param>
  <param-name>customDomainLangs</param-name>
  <param-value>www.site.co.jp:ja,www.site.com/english:en</param-value>
</init-param>

この設定は urlPattern = customDomain の設定と一緒にのみ使用することができます。

この設定を使用する場合、supportedLangs で宣言された各言語にカスタムドメインを与えなければなりません。逆に、各カスタムドメインの言語も supportedLangs で表現されなければなりません。

最後に、オリジナル言語のために宣言されたパスは、基礎となるウェブサーバーの構造と一致していなければなりません。 尚、この設定を使用してオリジナル言語のコンテンツのリクエストパスを変更することはできません。

追加のデバッグ機能を有効にするフラグです。

パラメータを true に設定して debugMode をオンにします。

<init-param>
  <param-name>debugMode</param-name>
  <param-value>true</param-value>
</init-param>

debugModeをオンにすると、wovnjavaの動作を変更するために2つの追加のクエリパラメータが利用可能になります。

リクエスト例: http://example.com/page/top.html?wovnCacheDisable

クエリパラメータとして wovnCacheDisable を使うと、wovnjavaは翻訳APIキャッシュをバイパスし、翻訳が常に再処理されるようになります。 これによりリクエストは遅くなりますが、更新された動作を確認するのに便利な場合もあります。 (クエリパラメータ wovnCacheDisable がない同じページのリクエストに対して、キャッシュをクリアしたり、動作を変更したりすることはできないことに注意してください)。

リクエスト例: http://example.com/page/top.html?wovnDebugMode

クエリパラメータとして wovnDebugMode を使用すると、サーバから送られてくるレスポンスHTMLに埋め込まれたデバッグ情報が有効になります。 これは、何かがサーバ上のwovnjavaで正しく動作していない場合、問題が何であるかをよりよく理解することを目的としています。

wovnCacheDisable および wovnDebugMode は、wovnjava の設定で debugMode がオンになっている場合にのみ利用可能であることに注意してください。