Facebook開発者向けドキュメントの日本語訳とTips

Understanding Locales

Facebookがサポートしているロケールは XML fileの通りです。

このロケール定義はISO languageとcountry codesに従っていて、アンダースコアで連結されています。基本のフォーマットは"ll_CC"で、llは２文字で成り立つ言語コード、CCは２文字で成り立つ国コードです。例えば、"en_US"はUS English（アメリカ英語）を示します。

しかしながら、ISO標準に従っていない例外が２つあります。ar_ARとes_LAの２つで、アラビア語とスペイン語の傘下となっている地域をカバーするためにそのような仕様になっています。後述するような、より特別なスペイン語圏のローカライズはケースは含まれていません。

User Graph APIのlocale情報から、ユーザのロケールを知ることができます。

Support Locales in Social Plugins and the JavaScript SDK

social pluginをIFrameで表示する場合、ユーザのロケール情報を基に自動的に翻訳します。XFBMLを使う場合、該当するロケールのJavaScript SDKを読み込む必要があります。例えば、スペイン語で表示する場合は以下のscriptを読み込みます。

http://connect.facebook.net/es_LA/all.js

Internationalizing your Application

以下のステップは皆、あなたがアプリケーションを作成済みでアプリケーションIDを所有しているという前提で進みます。

• Preparing your application for translation
• Registering the text you want translated
• Marking up text for translation
• Getting your application translated
• Managing the translation process
• Best practices

Preparing Your Application for Translation

Facebook Translationsフレームワークに入力するためには、まずアプリケーションのメインの言語を指定し、どの言語に翻訳するかを決定します。

Selecting Your Native Language

1. My Applications page へ行きます。
   
2. 翻訳したいアプリケーションを選択します。
3. BasicタブのLanguageの項目を、アプリケーションのメインの言語を指定します。 これでアプリケーションのネイティブ言語が決まります。

Choosing Languages for Translation

ネイティブ言語の指定が完了したら、今度はどの言語に翻訳するかを指定します。

1. Translations admin panelへ行き、右上のドロップダウンメニューから翻訳したいアプリケーションを選択します。　　
2. 任意のロケールへの翻訳を可能にするには、適切なLanguageの列を選択し、そのロケールのチェックボックスをOnにします。チェックすると、ユーザはあなたがtranslatableにマークした文字列を閲覧できるようになり、それらの翻訳を提供できるようになります。
   注意：チェックボックスが選択されていない場合、アプリケーションの翻訳をできるのは、開発者とLanguage Managersカラムに言語マネージャーとして登録されている人のみです。

翻訳プロセスを設定し終わると、他にもadministrationプロセスが必要な場合はTranslationsダッシュボードへと誘導されます。現状、このステップは必須となっています。

Registering the Text You Want Translated

いろいろな箇所のテキストを翻訳の対象とすることができます。全てのテキストが翻訳可能になっているかどうかが重要です。以下は、翻訳プロセスの準備をするうえで留意すべき箇所の包括的なリストです。

Text that gets rendered within your application or website.

FBMLもしくはXFBMLの マークアップタグ を翻訳対象のテキストに対して使用します。

Text entered on facebook.com.

アプリケーションに関するスタティックなテキストとして、facebook.com上で入力して翻訳対象に加えられるものがあります。それぞれのフィールドは、Facebook上に登録／更新されると、Translationsアプリケーションに登録されます。

• アプリケーション名
• アプリケーションの説明
• タブ名
  
• 添付テキスト
• Application Profile画面の説明文
  
• 開発者について

フィールドの翻訳の準備ができると、それ以上の開発者の干渉なしにFacebook上で使われるようになります。

Text sent through Facebook communication channels (like stream attachments).

FBML internationalization markup tagsでテキストを囲います。それから、実際に送信される前に対象テキストを登録したいのならばintl.uploadNativeStringsを用います。

Text contained within your databases.

直接レンダリングされないコンテンツを持つことも可能です。たとえばオンラインストアのアプリケーションを持っているとして、商品の名前を保持しようとしたとします。これらのテキストを翻訳対象とするには、intl.uploadNativeStringsを使ってデータベース中の全部の値を登録します。

注意：この方法は、頻繁に変わったりユーザによって生成される文字列に対して使われるべきではありません。一定の期間に登録できる文字列の量は定められていますので、ダイナミックなコンテンツを翻訳対象にしないというのは重要です。

Text contained within images or other non-text-based representations.

画像中に含まれるテキストや文字でない情報は、Facebook Translationsを用いて直接翻訳することができません。国際化された画像を用いたいのであれば、サポート対象となる全言語で画像を作り、ユーザのロケールによって表示を切り替えるべきです。

Marking Up Text for Translation

構造化されたテキストをFacebook Translationsに登録するには、FBMLやXFBMLタグを用いる方法があります。

• fb:intl -- テキストを翻訳可能にする主要なタグです。
• fb:intl-token -- fb:intl内に含まれているトークンとコンテンツを差し替えます。
• fb:tag -- HTMLタグを生成します。fb:tag-attributeと一緒に使う必要があります。
• fb:tag-attribute -- fb:tagで指定された、翻訳対象となるべきHTMLアトリビュートの値を含みます。
• fb:tag-body -- fb:tagで指定されたHTMLタグのコンテンツを持ちます。fb:tag-attributeが必要な場合にのみ有効です。
• fb:date -- 閲覧ユーザのロケールに従って日付を表示します。
• fb:fbml-attribute -- fb:tag-attributeに似て、FBMLタグのアトリビュートの値を持っていて、その値を翻訳可能にします。（FBMLのみです）　
• fb:window-title -- IFrameのタイトルを翻訳可能にします。Facebook Connectを利用したウェブサイトにのみ有効です。（XFBMLのみです）

Example Code

以下のようなFBMLをアプリケーション内に書き出しているとしましょう（サイト上のXFBMLでも構いませhん）

Give <fb:name uid="4800348" useyou="false" firstnameonly=true/> 
a copy of "Catcher In the Rye"?

FBMLをレンダリングするとき、適切な英文の'Give James a copy of "Catcher In the Rye"?'を返します。しかしながら、翻訳可能な形式で書き出すには、以下のように書かなくてはなりません。

<fb:intl desc="Asking whether user wants to give a book to someone">
  Give <fb:name uid="4800348" useyou="false"/> a copy of "{book-title}"?
  <fb:intl-token name="book-title">
      Catcher In the Rye
  </fb:intl-token>
</fb:intl>

このコードに関して、以下の点に気をつけてください。

• 実際の本のタイトルにそのまま出て欲しくはないので、可変値（本のタイトル）は中括弧で囲います。この文字列は、説明文を元に翻訳者が翻訳するものです。 fb:intl-token でテキストを囲むことで、レンダリング時に可変値と置換されます。nameアトリビュートは中括弧の中の値と同じでなくてはなりません。これらの要素は通常は異なる順番で出てきても大丈夫ですが、読み易さや書き忘れ防止の観点から、上記のような書方をするべきです。
  
• ほかの翻訳対象のメセッセージには、fb:name があります。このタグは、文字列が翻訳者に対して提供される際にトークンとして表示されます。ただし、トークンはFacebookの翻訳システムによって挿入されます。翻訳者が見る文字列は"Give {name} a copy of "{book-title}"?"のようなものになります。

FBML内で上記のようなタグが使われると、最初にキャンバスページがロードされた段階でTranslationsアプリケーションにアップロードされます。それ以降、Translationsアプリケーション内部とインライン両方で翻訳可能になります。一度テキストが（たとえばスペイン語に）翻訳されると、スペイン語ユーザにはそれが表示されるようになります。

Best Practices

どのようにして準備するのが一番いいかということに関しては、 best practicesを呼んで頂くとはっきりしてきます。そうすることを強くお薦めします。

Getting Your Application Translated

これで準備が完了し、翻訳対象となる全テキストが登録されましたので、翻訳が開始されます。いかなるFacebookユーザでもあなたのアプリケーションを翻訳することが可能ですが、アプリケーションのユーザに限ってしまう方が簡単です。

ユーザは以下の２つの方法で翻訳することが出来ます。

• アプリケーションの利用中にインラインで。
• 一度に複数のテキストを翻訳する簡単な方法として、Translationsアプリケーション上でまとめて翻訳。

Inline Translations

ユーザがインラインでの翻訳を可能な設定にしている場合、インラインで翻訳することが出来ます。以下のスクリーンショットが、インライン翻訳がユーザにとってどのように見えるかを説明してきます。下線が引かれている文字列は、テキスト上で右クリックするだけで翻訳（と投票）できる対象です。

ユーザは、ステータスバーのTranslationsダイアログのリンクをクリックすることでインライン翻訳を可能にできます。

Bulk Translation

Translationアプリケーションには、翻訳者が多くのテキストを同時に効率よく翻訳できるようにするインターフェースがあります。そこへユーザを誘導するには、http://www.facebook.com/translations/index.php?translate?app=<YOUR_APP_ID> へのリンクを置いてください。


Learn More

アプリケーションがどのようにして翻訳されるかを知る一番の方法は、試してみることです。Facebook Translationsアプリケーションには、翻訳を開始する為のhelp guideがあります。プロセスを理解する助けになるかもしれません。

Managing the Translation Process

Translations管理画面を用いて、アプリケーションの翻訳プロセスを管理できます。

1. まず、Translations admin panelに行きます。デフォルト選択されているのが管理したいアプリケーションではない場合は、右上のドロップダウンメニューから正しいものを選択してください。
   
   
   
   
2. 翻訳可能にする：アプリケーションを特定の言語へ翻訳するには、まず適切な言語を選択し、そしてチェックボックスをチェックします。そうすると、あなたが翻訳対象とした文字列をユーザが閲覧／翻訳できるようになります。注意：チェックボックスがチェックされていない場合、翻訳することができるのはアプリケーション開発者（Facebook Developerアプリケーションに一覧があります）と言語マネージャーのみです。
3. 翻訳された文字列のレビュー：Languageカラムの該当言語のリンクをクリックします。Browse Phrasesタブへと誘導されます。
   
4. 翻訳の進捗をチェックする：Translation/Approval Progressカラムのプログレスバーを見ると、テキストの何パーセントが翻訳され、承認されたかをチェックすることができます。
   
5. 言語マネージャーを指定する：Language Managersカラムで、どのFacebookユーザが翻訳を監督できるか指定できます。アプリケーションが全翻訳者に公開されているかに関わらず、これらのユーザは翻訳を閲覧／追加／削除することができます。
   
6. 対象言語で公開する：十分に翻訳できたと判断した場合、青いPublishリンクをクリックします。リンクが緑のPublishedへと変わり、該当ロケールのユーザはその言語で閲覧することになります。また、あなたのアプリケーションがFacebook Application Directoryに足された場合、新しく公開されたロケールで表示されます。
   

Accessing Your Translations

翻訳対象として登録したテキストへのアクセス方法は何通りもあります。これらの方法によって得た翻訳データは、保存したり利用したりすることができます。

いつでも Translations admin consoleを用いることでテキストを閲覧／編集できます。ただし現在のところ、コンソール画面から翻訳内容をエクスポートすることはできません。が、機械的に翻訳データを取得することも可能です。機械的に翻訳データにアクセスするには以下の２通りの方法があります。

• APAIのintl.getTranslationsメソッドを用いる方法：この方法を用いると、任意の言語に対する全翻訳内容を簡単に得ることができます。
• FQLのtranslationテーブルを用いる：翻訳データの任意のデータセットを取得します。

Best Practices

テキストをコード中に書き込む過程で色々な前提条件が出てきますが、必ずしも全ての言語で思い通りに伝わるわけではありません。アプリケーションを色々な言語や曖昧さに対応させるために、Facebook internationalizationチームが習得したベストプラクティスを紹介します。特に記されていない限り、以下のサンプルはFBMLとXFBML両方のマークアップに対応しています。

Be Descriptive

一般的に言って、２０文字以下のテキストは説明文を持つべきです（descアトリビュートを用います）。たとえば"Poke"という単語は名詞で使うか動詞で使うかで変わってしまいます。Facebook Translationsは、該当フレーズのテキストと説明文のハッシュを生成します。つまり、オリジナルのテキストもしくは説明文に僅かな変更があっただけでも、それは真新しいものとして認識されます。ですので、あとから書き直さなくて良いように完璧な説明文で書きます。以下の書式で書きます。

<fb:intl desc="Label for name of photo album">Name:</fb:intl>

言語によっては、人／場所／オブジェクトの何を示すかによってnameという単語は変わってしまいます。ここにある説明文によって、翻訳者は該当単語に対する最適なラベルを選択できます。説明文は、意味だけでなく文脈も示すべきです。リンクの文言など、長い文の一部に表記されるものにとっては特に重要です。なので、このようにします。

<fb:intl desc="In, 'X's photos are ready to view.'">{name}'s photos</fb:intl>

主語として使われるか目的語として使われるかによって名詞が変わる言語もありますが、この説明文があることによって、翻訳者は正しい形式を選べるようになります。

Don't Translate Markup

HTMLマークアップを翻訳文字列に含まず、複数の翻訳対象に分けてください。

そうしない限り、翻訳者はあなたのマークアップをも編集できることになってしまいます。決して、<a>タグのように行動が伴うものを翻訳文字列に含んではいけません。アンカータグを扱うより良い方法は以下の通りです。

<fb:intl>Click {=here} to continue.
  <fb:intl-token name="=here">
<a href="xyzzy">
  <fb:intl desc="In 'Click here to continue'">here</fb:intl>
</a>
  </fb:intl-token>
</fb:intl>

Use CSS instead of Markup

ページの一部のテキストに境界を持たせたりテキストに対してスタイルを指定する場合には、マークアップよりもCSSを使うようにしてください。例えば、"Next Page"という文字列があり、二行に分けて表示したいとします。その場合は、<br>によって分けるよりも、最大幅を指定したdivで囲うようにしてください。翻訳者が必要に応じて語順を変えるなどできなくなってしまうので、個々の翻訳テキストに分けてしまうのは良くありません。

以下のような書方は間違いです。

<fb:intl>Next<br/>Page</fb:intl>

<fb:intl>Next</fb:intl><br/><fb:intl>Page</fb:intl>

もし、言語によって"Page"が"Next"よりも先にくる必要があるとした場合、的確に訳すことができなくなってしまうからです。

以下のようにしてください。

<div class="limited-width-box"><fb:intl>Next Page</fb:intl></div>

適切なCSSを書くことで、ブラウザ上で適切に改行して表示されます。

Translating Attributes of HTML Tags

HTMLタグの中には、任意の文字列をアトリビュート中に含めるものがあります。たとえばinputタグの"value"アトリビュートや画像のaltです。これらを翻訳対象にするには、fb:tag-attribute用います。formのマークアップは以下のようにします。

<input type="submit"> 
  <fb:tag-attribute name="value"> 
    <fb:intl desc="Button action: Submit a form">Click here</fb:intl> 
  </fb:tag-attribute> 
</input>

Avoid Layouts Relying on Precise Sizing

オリジナルの言語で書かれた文字列の正確な表示サイズに依存するようなレイアウトは避けてください。他の言語に置き換えると、短くなったり長くなったりしてしまいます。テキストがぴったりと収まるようなサイズにしてしまった場合、より長い単語を用いる言語では正しく動作しないでしょう。

Assume Word Order Will Change

翻訳者が個々の文の語順を変えなくてはいけないことを想定に入れておいてください。厳密に言うと、小さな翻訳可能な断片で文を構成するのは良くありません。たとえ素晴らしい説明文を添えたとしても、翻訳者が文法的に正しい翻訳をすることを妨げてしまい兼ねないからです。その代わり、起こりうるケースそれぞれを別個の翻訳対象としておいて、完全な文としてコードを生成します。

以下は避けるべき例です。

<fb:intl>You are eating</fb:intl> <fb:intl>at home.</fb:intl>
<fb:intl>You are eating</fb:intl> <fb:intl>at a restaurant.</fb:intl>

上記の例では文の前半を書き出しているコードがありますが、ここは英語の場合には変更されず、後半だけが切り替わります。しかし、"at home"や"at a restaurant"が"eating"の前に来るべき中国語の用な言語では、正しく書き換えることは不可能です。

このような場合は、以下のように個々のフレーズを用いてください。

<fb:intl>You are eating at home.</fb:intl>
<fb:intl>You are eating at a restaurant.</fb:intl>

これなら、完全な文２つのうちの正しい方を選択できますし、翻訳者は必要に応じて語順を変えることができます。また、正しく全言語へ翻訳することが可能です。

もしくは、"You Have {number} photos."という文があるとして、個数が１なら"photo"と表記したいとします。そのような場合も、"You have one photo."と"You have {number} photos"の２つの文に分けてください。

以下のようにです。

<fb:intl>You have one photo.</fb:intl>

<fb:intl>You have {number} photos.
    <fb:intl-token name="number">5</fb:intl-token>
</fb:intl>

Don't Hardcode Punctuation

異なる言語は異なる句読点を用います。たとえば中国語は２種類の異なるカンマを文脈によって使い分けます。また、日本語はピリオドとは異なる独自の読点を用います。一般的に、完全な文を翻訳させるには（ピリオドやカンマを含む）、大きな問題にはなりません。なので、句読点もfb:intlタグの中に含めるべきです。

<fb:intl>You have mail.</fb:intl>

<fb:intl>Favorite color:</fb:intl> &lt;input ...>

翻訳対象の文字列にコロンを含むことで、翻訳者は代替の句読点を用いる、もしくは文字列とコロンの間に空白文字を用いる（フランス語など）ことが出来ます。

Messing with Your <head> (XFBML Only)

一般的に言って、XFBMLはページ内の<body>タグ内部であればどこでも機能します。しかしながら、ブラウザウィンドウのtitleは含まれません。XFBMLがパースされる範囲のどこかにfb:window-titleを用いることで含めることができます。タグ内のレンダリングされた内容がドキュメントタイトルとして用いられます。以下のようにして翻訳されたタイトルを提供できます。

<fb:window-title> 
  <fb:intl desc="Title of a Web page">Welcome!</fb:intl> 
</fb:window-title>