Java ライブラリ

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

動作要件

ライブラリ方式動作要件を参照してください。

ライブラリ方式の動作概要

ライブラリ方式における動作概要を参照してください。

インストール手順

Java アプリケーションの設定（Maven による設定）

インフォメーション
Maven 以外の環境をお使いの場合は、こちらの設定方法を参照してください。

本ライブラリを組み込むアプリケーションの pom.xml に、JitPack のリポジトリを追加してください。

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </snapshots>
  </repository>
</repositories>

アプリケーションの pom.xml の依存関係に、本ライブラリを追加してください。

<dependency>
  <groupId>com.github.wovnio</groupId>
  <artifactId>wovnjava</artifactId>
  <version>x.x.x</version>
</dependency>

使用可能なライブラリのバージョンはこちらのページを参照してください。

ライブラリの設定をアプリケーションの web.xml に記述してください。
必須パラメータは以下の通りです。

projectToken
defaultLang
supportedLangs
urlPattern

設定したパラメータの projectToken と作成した WOVN プロジェクトのプロジェクトトークンが正しく一致している必要があります。
ご注意ください。

設定サンプル

以下は、元言語が日本語、翻訳言語が英語の場合のサンプルです。
また、WOVN プロジェクトトークンは 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>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>FORWARD</dispatcher>
</filter-mapping>

設定オプション

パラメータ名	必須	初期設定
defaultLang	◯
projectToken	◯
supportedLangs	◯
urlPattern	◯
customDomainLangs
debugMode
enableFlushBuffer		false
ignoreClasses
ignorePaths
langCodeAliases
originalQueryStringHeader
originalUrlHeader
sitePrefixPath
useProxy		false

defaultLang

対象の Web サイトが使用する元言語です。
このパラメータは 2 文字からなる言語コードで記入します。
言語コードの一覧は言語地域コードを参照してください。

projectToken

WOVN のプロジェクトトークンを設定します。
トークンの取得方法についてはトークンの確認方法を参照してください。

supportedLangs

WOVN プロジェクトで設定した翻訳言語を記述します。元言語は自動的にこのリストに追加されます。
カンマ区切りで言語コードを指定します。
例：en, zh-CHT, zh-CHS

urlPattern

WOVN Java ライブラリは Java アプリケーションに翻訳ページ用の新しい URL を追加します。
urlPattern パラメータには、このときに設定する URL のパターンを指定できます。

URL のタイプには下記 4 種類があります。
各パターンのメリット・デメリットについては各URLパターンの特徴を参照してください。

パターンタイプ	言語切替後のURL
"path"	https://wovn.io/en/contact
"subdomain"	https://en.wovn.io/contact
"query"	https://wovn.io/contact?wovn=en
"customDomain"	下記記載を参照してください

customDomainLangs

インフォメーション
このパラメーターは urlPattern パラメーターで customDomain を設定している場合のみ有効です。

利用する言語に応じたドメインおよびパスをカスタム定義できます。
設定フォーマットとサンプルは以下の通りです。

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

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

baseURL には、ホスト名とパスのみが含まれるようにしてください。https:// や https:// は必要ありません。
また、ポート番号は必要ありませんが、全てのサブドメインは正しく記載されている必要があります。
上記の例では、下記のように処理します。
- www.site.co.jp に対する全てのリクエストを日本語として処理します。
- www.site.com/english/* に対する全てのリクエストを英語として処理します。
www.site.com/admin のようにドメイン言語と一致しないリクエストは、WOVN Javaライブラリによって処理されません。
上記の構成例では、英語のページ https://www.site.co.jp/about.html の英語版 URL は https://www.site.com/english/about.html として処理されます。

これらに対応する 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>

必須事項

customDomainLangs パラメーターは urlPattern が customDomain 形式の場合のみ有効です。

本パラメーターを使用する場合、supportedLangs で宣言されている各言語に対してカスタムドメインを指定する必要があります。
逆に、各カスタムドメインで指定した言語を supportedLangs で示す必要があります。

また、元言語用に宣言されたパスは、基となる Web サーバの構造と一致する必要があります。
つまり、この設定を使用して元言語のコンテンツリクエストパスを変更することはできません。

debugMode

デバッグログの出力が有効になります。
有効にするには、以下のように定義してください。

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

この debugMode パラメータを有効にすると、エンドユーザーが Web サイトを表示する際、WOVN Java ライブラリは以下の 2 つのクエリパラメータを付加します。

wovnCacheDisable

リクエストのサンプル：https://example.com/page/top.html?wovnCacheDisable
WOVN Java ライブラリは翻訳 API キャッシュを使わずに動作し、常に翻訳データを WOVN サーバーから取得します。
これによりリクエスト、レスポンスが遅くなりますが、更新された動作を確認する場合に有効です。

wovnDebugMode

リクエストのサンプル：https://example.com/page/top.html?wovnDebugMode
サーバから送信されるレスポンス HTML に埋め込まれたデバッグ情報が有効になります。
これは、サーバ上の WOVN Java ライブラリで何が正しく機能していないのかを特定するためのものです。

enableFlushBuffer

ServletResponse.flushBuffer(). が定義されている場合のオプション設定です。
このパラメータの初期設定は false です（推奨値）。

enableFlushBuffer が false の場合、WOVN Java ライブラリはクライアントに対するコンテンツの書き込みを行うことなく、response.flushBuffer() の呼び出しを取得します。
完全な HTML レスポンスの準備ができた段階でフィルターがコンテンツを翻訳し、クライアントへレスポンスします。

ignoreClasses

WOVN に送信したくない HTML 要素に付与されている class をこのパラメータにカンマ区切りで指定すると、翻訳対象から除外できます。
翻訳除外された要素とコンテンツは、WOVN Java ライブラリに送信されたり、翻訳されることはありません。

以下は、 my-select-class クラスを持つ HTML タグの例です。

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

my-secret-class を ignoreClasses に登録すると、WOVN Javaライブラリは以下のように扱います。

<div></div>

上記のような振る舞いを my-secret-class, email-address-element, noshow クラスに対して行う場合は、以下のとおりパラメーターを設定します。

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

ignorePaths

WOVN Java ライブラリでは、指定のパスを翻訳対象から除外できます。

<init-param>
  <param-name>ignorePaths</param-name>
  <param-value>/admin,/wp-admin</param-value>
</init-param>

langCodeAliases

WOVN で設定している言語が持つ言語コードに、任意のエイリアスを設定できます。

例えば、初期設定では英語の言語コードは en になっています。
そのため、英語ページにアクセスするときの URLは https://example.com/en/page のようになります。
langCodeAliases を使うと、受け付ける言語コードを en ではなく us のように置き換えることができます。
この場合の URL は https://example.com/us/page となります。

このパラメーターはパス形式、クエリ形式、サブドメイン形式の全てで利用できます。
設定は下記フォーマットに従ってください。

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>

デフォルト言語へのエイリアス

WOVN の導入に関係なく、元々言語コードを含むディレクトリパスの中に既存コンテンツが存在する場合、デフォルト言語にエイリアスを設定できます。
このパス、またはサブドメインを言語コードとして WovnServlertFilter に処理させることが出来ます。

例えば、翻訳したいコンテンツが https://example.com/jp/* にあり、このサイトの元言語は日本語の場合、https://example.com/jp/home.html が https://example.com/en/home.html になるよう、英語の翻訳コンテンツ URL で /jp/ を /en/ に変更する必要があります。
この場合、jp を日本語のエイリアスとして設定することで対応が可能です。

originalUrlHeader, originalQueryStringHeader

Apache HTTP Server の mod_rewrite モジュールなどを使用して URL を書き換えている場合、WOVN Javaライブラリには書き換え前の URL が渡されず、適切な翻訳データを取得できない場合があります。originalUrlHeader、originalQueryStringHeader を設定した場合、WOVN Javaライブラリはこれらに設定されたリクエストヘッダの値を翻訳データの取得に利用します。

下記の Apache HTTP Server の設定で、書き換え前の URL をリクエストヘッダに設定した場合、

SetEnvIf Request_URI "^(.*){{content}}quot; 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"

WOVN Java ライブラリは、下記の設定で書き換え前の URL を使い、正しい翻訳データを取得できます。

<filter>
  ...
  <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>
  ...
</filter>

サンプル引用元：https://coderwall.com/p/jhkw7w/passing-request-uri-into-request-header

sitePrefixPath

WOVN がページを変換するアンカーとして使用するプレフィックスパスを設定できます。
この設定では、WOVN はプレフィックスパスに一致するページのみを変換し、パス言語コードがプレフィックスパスの後に追加されます。

以下は sitePrefix に city を設定した場合のサンプルです。

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

WOVN は、以下のページ URL に一致した場合のみ翻訳処理を行います。

https://www.mysite.com/city/*

例えば、URL：http://www.mysite.com/city/tokyo/map.html は翻訳され、言語コードが付与された状態の URL にアクセスできます。
例： http://www.mysite.com/city/en/tokyo.map.html.

初期設定では、ドメイン配下の全てのページが翻訳、言語コードの付与対象として動作します。

必須事項

このパラメータは、urlPattern が path 形式の場合のみ有効です。
加えて、web.xml に対して WovnServletFilter に対応するフィルターマッピングでの構成をおすすめします。

上記の例の様に、プレフィックスパスが city に設定されている場合、対応するフィルターマッピングは次の通りになります

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

useProxy

リバースプロキシの使用時、WOVN Java ライブラリに適切なホスト名が渡されず、翻訳ページのデータを取得できない場合があります。
useProxy に true を設定すると、WOVN Java ライブラリの処理に HTTP リクエストヘッダの X-Forwarded-Host を使用します。

使用方法は以下の通りです。

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

動作不具合に関するお問い合わせ

WOVN の Java ライブラリ（WOVN.java）をご利用の上でご不明な点や、動作しない点がある場合は、WOVN 管理画面右上の「お問い合わせ」ボタンからお問い合わせください。

このセクションの記事

Javaライブラリ

Java ライブラリ

目次

動作要件

ライブラリ方式の動作概要

インストール手順

Java アプリケーションの設定（Maven による設定）

設定サンプル

設定オプション

defaultLang

projectToken

supportedLangs

urlPattern

customDomainLangs

必須事項

debugMode

wovnCacheDisable

wovnDebugMode

enableFlushBuffer

ignoreClasses

ignorePaths

langCodeAliases

デフォルト言語へのエイリアス

originalUrlHeader, originalQueryStringHeader

sitePrefixPath

必須事項

useProxy

動作不具合に関するお問い合わせ