SharePoint Framework のクライアント側 Web パーツをローカライズするLocalize SharePoint Framework client-side web parts

世界中の SharePoint ユーザーによって話されているさまざまな言語にローカライズすれば、SharePoint Framework のクライアント側の Web パーツを広くアピールできます。この記事では、Web パーツをオランダ語 (オランダ) ロケールにローカライズし、ローカライズされた値が正しく表示されることを確認します。You can broaden the appeal of your SharePoint Framework client-side web part by localizing it for different languages spoken by SharePoint users all over the world. In this article, you will localize a web part to the Dutch (Netherlands) locale, and verify that the localized values are displayed correctly.

注意

この記事の手順を実行する前に、必ず SharePoint のクライアント側 Web パーツ開発環境を設定しておいてくださいBefore following the steps in this article, be sure to set up your SharePoint client-side web part development environment.

プロジェクトを準備するPrepare the project

新規プロジェクトを作成するCreate a new project

  1. プロジェクト用の新しいフォルダーを作成します。Create a new folder for your project:

    md react-localization
    
  2. プロジェクト フォルダーに移動します。Go to the project folder.

    cd react-localization
    
  3. プロジェクト フォルダーで SharePoint Framework Yeoman ジェネレーターを実行し、新しい SharePoint Framework プロジェクトをスキャホールディングします。In the project folder, run the SharePoint Framework Yeoman generator to scaffold a new SharePoint Framework project.

    yo @microsoft/sharepoint
    
  4. ダイアログ ボックスが表示されたら、次の値を入力します。When prompted, enter the following values:

    • ソリューション名: react-localizationreact-localization as your solution name.
    • ベースライン パッケージ セット: SharePoint Online のみ (最新)SharePoint Online only (latest) as the baseline package set.
    • ファイルの配置場所: [現在のフォルダーを使用する]Use the current folder for the location to place the files.
    • [y] を指定するとテナント全体の展開を許可にします。y to allow tenant-wide deployment.
    • 開発するコンポーネントの種類: Web パーツWebPart as the type of component to develop.
    • Web パーツ名: GreetingGreeting as your web part name.
    • Greets the user: Web パーツの説明。Greets the user as your web part description.
    • React: Web パーツをビルドする開始点。React as the starting point to build the web part.


    既定の選択肢を指定した SharePoint Framework Yeoman ジェネレーター

  5. スキャフォールディングが完了したら、次のコマンドを実行して、プロジェクトの依存関係のバージョンをロック ダウンします。After the scaffolding completes, lock down the version of the project dependencies by running the following command:

    npm shrinkwrap
    
  6. コード エディターでプロジェクト フォルダーを開きます。Open your project folder in your code editor. この記事の手順とスクリーンショットでは Visual Studio Code を使用していますが、お好きなエディターをどれでも使用できます。This article uses Visual Studio Code in the steps and screenshots, but you can use any editor that you prefer.

    Visual Studio Code で開いた SharePoint Framework のプロジェクト

既定のコードを置き換えるReplace the default code

  1. コード エディターで ./src/webparts/greeting/GreetingWebPart.ts ファイルを開き、IGreetingWebPartProps インターフェイスの定義を次のコードに更新します。In the code editor, open the ./src/webparts/greeting/GreetingWebPart.ts file and update the definition of the IGreetingWebPartProps interface to the following code:

    export interface IGreetingWebPartProps {
     greeting: string;
    }
    
  2. 同じファイルで GreetingWebPart クラスを次のように変更します。Next, in the same file and change the GreetingWebPart class to:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
    
     public render(): void {
       const element: React.ReactElement<IGreetingProps > = React.createElement(
         Greeting,
         {
           greeting: this.properties.greeting
         }
       );
    
       ReactDom.render(element, this.domElement);
     }
    
     protected get dataVersion(): Version {
       return Version.parse('1.0');
     }
    
     protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
       return {
         pages: [
           {
             header: {
               description: strings.PropertyPaneDescription
             },
             groups: [
               {
                 groupName: strings.DisplayGroupName,
                 groupFields: [
                   PropertyPaneTextField('greeting', {
                     label: strings.GreetingFieldLabel
                   })
                 ]
               }
             ]
           }
         ]
       };
     }
    }
    
  3. React の主要コンポーネントを更新するため、./src/webparts/greeting/components/Greeting.tsx ファイルを開いてコードを次のように変更します。Update the main React component by opening the ./src/webparts/greeting/components/Greeting.tsx file and changing its code to:

    import * as React from 'react';
    import styles from './Greeting.module.scss';
    import { IGreetingProps } from './IGreetingProps';
    import { escape } from '@microsoft/sp-lodash-subset';
    
    export default class Greeting extends React.Component<IGreetingProps, {}> {
     public render(): JSX.Element {
       return (
         <div className={styles.greeting}>
           <div className={styles.container}>
             <div className={`ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}`}>
               <div className="ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1">
                 <span className='ms-font-xl ms-fontColor-white'>
                   Welcome to SharePoint!
                 </span>
                 <p className='ms-font-l ms-fontColor-white'>
                   Customize SharePoint experiences using Web Parts.
                 </p>
                 <p className='ms-font-l ms-fontColor-white'>
                   {escape(this.props.greeting)}
                 </p>
                 <a href="https://aka.ms/spfx" className={styles.button}>
                   <span className={styles.label}>Learn more</span>
                 </a>
               </div>
             </div>
           </div>
         </div>
       );
     }
    }
    
  4. React の主要コンポーネント インターフェイスを更新するため、./src/webparts/greeting/components/IGreetingProps.tsx ファイルを開いてコードを次のように変更します。Update the main React component interface by opening the ./src/webparts/greeting/components/IGreetingProps.tsx file and changing its code to:

    import { IGreetingWebPartProps } from '../GreetingWebPart';
    
    export interface IGreetingProps extends IGreetingWebPartProps {
    }
    
  5. ローカライズ TypeScript 型定義ファイルを更新するため、./src/webparts/greeting/loc/mystrings.d.ts ファイルを開いてコードを次のように変更します。Update the localization TypeScript type definition file by opening the ./src/webparts/greeting/loc/mystrings.d.ts file and changing its code to:

    declare interface IGreetingWebPartStrings {
     PropertyPaneDescription: string;
     DisplayGroupName: string;
     GreetingFieldLabel: string;
    }
    
    declare module 'GreetingWebPartStrings' {
     const strings: IGreetingWebPartStrings;
     export = strings;
    }
    
  6. 英語 (米国) ロケール ファイルを更新するため、./src/webparts/greeting/loc/en-us.js ファイルを開いてコードを次のように変更します。Update the US English locale file by opening the ./src/webparts/greeting/loc/en-us.js file and changing its code to:

    define([], function() {
     return {
       "PropertyPaneDescription": "Greeting web part configuration",
       "DisplayGroupName": "Display",
       "GreetingFieldLabel": "Greeting to show in the web part"
     }
    });
    
  7. Web パーツのマニフェストで、greeting プロパティの既定値を更新するため、./src/webparts/greeting/GreetingWebPart.manifest.json ファイルを開いて properties セクションを次のように変更します。In the web part manifest update the default value of the greeting property by opening the ./src/webparts/greeting/GreetingWebPart.manifest.json file and changing the properties section to:

    {
     // ...
     "preconfiguredEntries": [{
       "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Other
       "group": { "default": "Other" },
       "title": { "default": "Greeting" },
       "description": { "default": "Greets the user" },
       "officeFabricIconFontName": "Page",
       "properties": {
         "greeting": "Hello"
       }
     }]
    }
    
  8. 次のコマンドを実行して、すべての変更が正しく適用されていることを確認します。Verify that you have applied all changes correctly by running the following command:

    gulp serve
    
  9. SharePoint ワークベンチで Web パーツをページに追加し、その構成を開きます。In the SharePoint workbench add the web part to the page and open its configuration.

    プロパティ ウィンドウが開かれているページに追加された案内応答 Web パーツ

Web パーツのマニフェストをローカライズするLocalize the web part manifest

SharePoint Framework のクライアント側の Web パーツはすべて、コードとマニフェストで構成されています。Every SharePoint Framework client-side web part consists of code and a manifest. マニフェストは、タイトル、説明、アイコンなどの Web パーツに関する情報を提供します。The manifest provides information about the web part such as its title, description, and icon. Web パーツをページに追加すると、Web パーツのマニフェストからの情報がユーザーに表示されます。When adding a web part to the page, the information from the web part manifest is displayed to users.

この情報を使用して、ユーザーは自分が探しているものがその Web パーツかどうか判断します。Using this information, users decide if the web part is the one that they are looking for. Web パーツを使用してもらうには、Web パーツの機能を正しく反映したタイトルと説明を入力する必要があります。Providing a title and description that correctly reflect the web part's functionality is essential if you want your web part to be used. 英語以外のサイトで Web パーツを使用する場合、そのメタデータをローカライズすれば、ユーザー エクスペリエンスはさらに向上します。If your web part is used on non-English sites, localizing its metadata can improve the user experience even further.

タイトルや説明など、Web パーツのマニフェストで定義されている一部のプロパティには、ローカライズされた値を指定することができます。Some properties defined in the web part manifest, such as title or description, support specifying localized values. ローカライズをサポートしている Web パーツのマニフェスト プロパティの完全な一覧については、「事前構成済みのエントリを使用して Web パーツの追加を簡略化する」を参照してください。For the complete list of all web part manifest properties that support localization read the Simplify adding web parts with preconfigured entries article.

ローカライズをサポートするプロパティの型は ILocalizedString です。Properties that support localization are of type ILocalizedString. ローカライズされる各文字列では、少なくとも既定値を指定しなければならず、必要に応じてその他のロケールの値を指定します。Each localized string must specify at least the default value and optionally values for other locales.

タイトル、説明、グループ名のローカライズされた値を追加するAdd localized values for title, description, and group name

  1. コード エディターで、./src/webparts/greeting/GreetingWebPart.manifest.json ファイルを開きます。In the code editor open the ./src/webparts/greeting/GreetingWebPart.manifest.json file.

  2. preconfiguredEntries 配列で、コードを次のように変更し、titledescriptiongroup プロパティの翻訳をオランダ語 (オランダ) で追加します。In the preconfiguredEntries array add translations for the title, description, and group properties in Dutch (Netherlands), by changing the code to:

    {
     // ...
     "preconfiguredEntries": [{
       "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Other
       "group": { "default": "Other", "nl-nl": "Anders" },
       "title": { "default": "Greeting", "nl-nl": "Begroeting" },
       "description": { "default": "Greets the user", "nl-nl": "Begroet de gebruiker" },
       "officeFabricIconFontName": "Page",
       "properties": {
         "greeting": "Hello"
       }
     }]
    }
    
  3. 次のコマンドを実行して、プロジェクトが動作していることを確認します。Run the following command to verify that the project is working:

    gulp serve
    

注意

現在、SharePoint ワークベンチでは、Web パーツのマニフェストからローカライズされた値をプレビューすることはサポートされていません。Unfortunately, the SharePoint workbench doesn't currently support previewing the localized values from the web part manifest. 既定値の翻訳が常に使用されます。It always uses the default translation.

Web パーツのプロパティ ウィンドウのローカライズLocalize the web part property pane

Web パーツを使用する場合、ユーザーはたいてい特定のニーズに合わせて Web パーツを構成する必要があります。When working with a web part, a user often needs to configure it for their specific needs. さまざまな構成設定を説明するラベルを指定することにより、Web パーツの操作性は向上し、Web パーツの構成についてユーザーから寄せられるサポート要求の数が減少します。When working with web parts users often need to configure it for their specific needs. Providing descriptive labels for the different configuration settings improves the usability of the web part, and decreases the number of support requests from users for help configuring web parts.

Web パーツのプロパティ ウィンドウは、複数のセクションで構成されます。The web part property pane consists of sections. 各セクションには 1 つのヘッダーと、ユーザーが Web パーツを構成するための 1 つ以上のコントロールが含まれます。Each section has a header and one or more controls that allow users to configure the web part. これらの各コントロールには、その目的を説明するラベルが含まれています。Each of these controls contains a label that describes its purpose.

既定では、Web パーツは、JavaScript リソース ファイルから文字列ラベルを読み込みます。By default, web parts load the string labels from a JavaScript resource file. 完全信頼ソリューションを使用して従来の Web パーツを構築した場合、これらは .resx リソース ファイルに類似したものになります。If you've built classic web parts with full-trust solutions, they resemble .resx resource files. これらのリソース ファイルを必ず使用する必要はなく、コードに文字列を直接含めることもできます。It's not required to use these resource files, and you could include the strings directly in code. しかし、リソース ファイルを使用することを強くお勧めします。However, it's highly recommended that you use resource files. それに伴う若干のオーバーヘッドは、後で Web パーツを翻訳しなければならなくなった場合に必要になる、すべてのラベルを後から抽出する労力を補って余りあります。The little additional overhead they add outweighs the effort required to extract all labels afterwards should you need to translate the web part later on.

Web パーツで使用されるローカライズ ファイルは、./src/webparts/greeting/loc フォルダーに格納されています。The localization files used by the web part are stored in the ./src/webparts/greeting/loc folder.

SharePoint フレームワークのクライアント側の Web パーツで使用されるローカライズ ファイルが Visual Studio Code で強調表示されている


loc フォルダーには、ローカライズされたファイルに含まれるさまざまな文字列を TypeScript に通知する TypeScript 型定義ファイル (./src/webpart/greeting/loc/mystrings.d.ts) が含まれます。The loc folder contains a TypeScript type definition file (./src/webpart/greeting/loc/mystrings.d.ts) that informs TypeScript of the different strings included in the localized files. このファイルの情報を使用することにより、コード内の文字列を処理するときにコード エディターで IntelliSense を使用できます。Using the information from this file, your code editor can provide you with IntelliSense when working with strings in code. さらに、TypeScript は、プロジェクトのビルド中に、定義されていない文字列が参照されていないか検証できます。Additionally, while building your project, TypeScript can verify that you're not referring to a string that hasn't been defined.

Visual Studio Code においてローカライズされた文字列に対応する IntelliSense


Web パーツでサポートされているロケールごとに、翻訳済みの文字列が入ったプレーン JavaScript ファイル (TypeScript ではありません) もあります。これには、ロケールに基づく小文字の名前が付いています (例: en-us.js)。For each locale supported by your web part, there is also a plain JavaScript file (not TypeScript) named in lowercase after the locale (for example en-us.js) containing the translated strings.

新しい SharePoint Framework プロジェクトでスキャフォールディングされた標準ローカライズ ファイル


重要

ローカライズ用の TypeScript 型定義ファイルで指定されているすべてのキーが、すべてのローカライズ JavaScript ファイルで翻訳されていることを特に注意深く確認する必要があります。Important: You should pay extra attention to verifying that all keys specified in the TypeScript type definition file for localization have translations in all localization JavaScript files.

SharePoint Framework で使用される既定のロケールは、en-us (英語) です。en-US is the default locale used by the SharePoint Framework. Web パーツでサポートされていないロケールのサイトで Web パーツが使用される場合、SharePoint Framework は、既定のロケールとして en-us (英語) を使用します。If your web part is used on a site using a locale not supported by your web part, the SharePoint Framework will use en-US as the default locale.

優先言語の翻訳を記載した default.js というロケール ファイルを作成すれば、この動作を上書きできます。You can override this behavior by creating a locale file named default.js with the translations in your preferred language. default.js という名前はロケールの名前付け規則に従っていませんが、SharePoint フレームワークのビルド プロセスに対し、標準の英語 (米国) ロケールではなく、その特定のロケール ファイルをフォールバック ロケールとして使用するよう通知します。While the name default.js doesn't follow the locale naming convention, it signals to the SharePoint Framework build process to use that particular locale file as the fallback locale instead of the standard US English locale.

Web パーツのプロパティ ウィンドウの文字列のローカライズされた値を追加するAdd localized values for web part property pane strings

  1. ./src/webparts/greetings/loc フォルダーで、nl-nl.js という新しいファイルを作成し、次のコードを入力します。In the ./src/webparts/greetings/loc folder create new file named nl-nl.js and enter the following code:

    define([], function() {
     return {
       "PropertyPaneDescription": "Instellingen van het begroeting webonderdeel",
       "DisplayGroupName": "Weergave",
       "GreetingFieldLabel": "Begroeting die in het webonderdeel getoond wordt"
     }
    });
    
  2. ローカライズ用の TypeScript 型定義ファイルのキーが、英語 (米国) およびオランダ語 (オランダ) のロケール ファイルの内容と一致することを確認します。Verify that the keys in the TypeScript type definition file for localization match the contents of the locale files for US English and Dutch (Netherlands).

    ローカライズ用の TypeScript 型定義ファイルと、英語 (米国) およびオランダ語 (オランダ) のロケール ファイルが Visual Studio Code で並べて開かれている

ローカライズされた Web パーツのプロパティ ウィンドウの文字列を検証するVerify the localized web part property pane strings

SharePoint ワークベンチのホスト バージョンまたは開発者テナントのチーム サイトを使用して Web パーツをテストする場合、spPageContextInfo.currentUICultureName プロパティによって表されるコンテキスト サイトのロケールが、既定のロケールとして使用されます。When testing web parts using the hosted version of the SharePoint workbench or team sites on a developer tenant the locale of the context site expressed by the spPageContextInfo.currentUICultureName property is used as the default locale.

ローカルの SharePoint ワークベンチを使用して Web パーツをテストする場合、SharePoint Framework は既定で en-US ロケールを使用して、Web パーツのプロパティ ウィンドウの文字列を表示します。When testing web parts using the local SharePoint workbench, the SharePoint Framework uses by default the en-US locale to display web part property pane strings. Web パーツでサポートされているその他のロケールからの値をテストする方法は 2 種類あります。There are two ways in which you can test the values from other locales supported by your web part.

プロジェクト構成でテストするロケールを指定するSpecify the locale to be tested in the project configuration

SharePoint ワークベンチでテストするロケールを指定する方法の 1 つは、プロジェクト構成を編集することです。One way to specify the locale to be tested in the SharePoint workbench is by editing the project configuration. この方法は、自分とチーム メンバーがあるロケールでより長い時間に渡って作業する場合や、英語 (米国) をサポートしない Web パーツを作成している場合に便利です。This approach is useful if you and your team members are working with a locale for a longer period of time or if you're building a web part that doesn't support US English.

  1. コード エディターで、./config/write-manifests.json ファイルを開き、次に示すようにコードを変更します。In the code editor open the ./config/write-manifests.json file and change its code to:

    {
     "cdnBasePath": "<!-- PATH TO CDN -->",
     "debugLocale": "nl-nl"
    }
    
  2. 次のコマンドを実行して SharePoint ワークベンチを起動します。Start the SharePoint workbench by running the following command:

    gulp serve
    

    ページに Web パーツを追加し、その構成を開くと、Web パーツのプロパティ ウィンドウの文字列がオランダ語 (オランダ) で表示されます。When you add the web part to the page and open its configuration you will see the strings in the web part property pane displayed in Dutch (Netherlands).

    オランダ語 (オランダ) で表示される Web パーツ プロパティ ウィンドウの文字列

コマンド ライン引数を使用してテストするロケールを指定するSpecify the locale to be tested using the command line argument

ローカルの SharePoint ワークベンチで使用するロケールを指定する別の方法は、それを gulp タスクの引数として指定することです。Another way to specify the locale to be used by the local SharePoint workbench is to specify it as an argument for the gulp task. Start the SharePoint workbench by running the following command:

  • 次のコマンドを実行して SharePoint ワークベンチを起動します。Start the SharePoint workbench by running the following command:

    gulp serve --locale=nl-nl
    

    Web パーツの構成を開くと、この場合も、すべてのプロパティ ウィンドウの文字列が既定の英語 (米国) ではなくオランダ語 (オランダ) で表示されます。Once again, when you open your web part's configuration you will see that all property pane strings are displayed in Dutch (Netherlands) rather than the default US English.

    オランダ語 (オランダ) で表示される Web パーツ プロパティ ウィンドウの文字列

Web パーツのコンテンツをローカライズするLocalize web part contents

Web パーツのプロパティ ウィンドウの文字列をローカライズするのと同じ方法で、Web パーツの本体に表示されるすべての文字列をローカライズする必要があります。The same way that you localize web part property pane strings, you should localize all strings displayed by the web part in its body. Web パーツのプロパティ ウィンドウの文字列をローカライズするときに使用するのと同じアプローチを使用することができます。You can use the same approach that you use when localizing web part property pane strings. ローカライズする文字列ごとに、ローカライズ TypeScript 定義ファイルにキーを追加してから、サポートされているロケールの JavaScript ファイルでその文字列を対応するロケールに翻訳します。The same way you localize web part property pane strings, you should localize all strings displayed by the web part in its body. You can use the same approach that you use when localizing web part property pane strings. For every string to be localized, add a key in the localization TypeScript definition file, and then translate the string to each of the supported locales in the corresponding locale JavaScript file.

Web パーツの文字列をグローバル化するGlobalize the web part strings

スキャフォールディングされる SharePoint Framework プロジェクトで提供される既定の Web パーツでは、文字列がコードに埋め込まれています。The default web part provided with the scaffolded SharePoint Framework project has its strings embedded in the code. これらの文字列をローカライズするには、まずそれをローカライズ対象文字列への参照に置き換える必要があります。Before you can localize these strings you have to replace them with references to the localized strings. このプロセスは多くの場合、グローバリゼーションまたは国際化 (または短縮して i18n) と呼ばれます。This process is often referred to as globalization or internationalization (or i18n for short).

  1. コード エディターで、./src/webparts/greeting/components/Greetings.tsx ファイルを開きます。In the code editor, open the ./src/webparts/greeting/components/Greetings.tsx file.

  2. ファイルの最上部セクションで、最後の import ステートメントの直後に、ローカライズ対象文字列への参照を追加します。In the top section of the file, directly after the last import statement, add a reference to the localized strings:

    import * as strings from 'GreetingWebPartStrings';
    
  3. Greeting クラスの内容を次のコードで置き換えます。Next, replace the contents of the Greeting class with the following code:

    // ...
    export default class Greeting extends React.Component<IGreetingProps, {}> {
     public render(): JSX.Element {
       return (
         <div className={styles.greeting}>
           <div className={styles.container}>
             <div className={`ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}`}>
               <div className="ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1">
                 <span className='ms-font-xl ms-fontColor-white'>
                   Welcome to SharePoint!
                 </span>
                 <p className='ms-font-l ms-fontColor-white'>
                   Customize SharePoint experiences using Web Parts.
                 </p>
                 <p className='ms-font-l ms-fontColor-white'>
                   {escape(this.props.greeting)}
                 </p>
                 <a href="https://aka.ms/spfx" className={styles.button}>
                   <span className={styles.label}>{strings.LearnMoreButtonLabel}</span>
                 </a>
               </div>
             </div>
           </div>
         </div>
       );
     }
    }
    

ローカライズ TypeScript 型定義ファイルに新しい文字列を追加するAdd the new string to the localization TypeScript type definition file

文字列を参照に置き換えたら、次の手順は、Web パーツで使用されるローカライズ ファイルにその文字列を追加することです。Having replaced the string with a reference, the next step is to add that string to the localization files used by the web part.

  • コード エディターで、./src/webparts/greetings/loc/mystrings.d.ts ファイルを開き、そのコードを次のように変更します。In the code editor open the ./src/webparts/greetings/loc/mystrings.d.ts file, and change its code to:

    declare interface IGreetingWebPartStrings {
      PropertyPaneDescription: string;
      DisplayGroupName: string;
      GreetingFieldLabel: string;
      LearnMoreButtonLabel: string;
    }
    
    declare module 'greetingStrings' {
      const strings: IGreetingWebPartStrings;
      export = strings;
    }
    

新しい文字列に相当するローカライズされた値を追加するAdd localized values for the new string

最後の手順は、新しい文字列に相当するローカライズされたバージョンを、Web パーツでサポートされているすべてのロケールで提供することです。The last step is to provide localized versions for the new string in all locales supported by the web part.

  1. コード エディターで、./src/webparts/greeting/loc/en-us.js ファイルを開き、次に示すようにコードを変更します。In the code editor, open the ./src/webparts/greeting/loc/en-us.js file and change its code to:

    define([], function() {
     return {
       "PropertyPaneDescription": "Greeting web part configuration",
       "DisplayGroupName": "Display",
       "GreetingFieldLabel": "Greeting to show in the web part",
       "LearnMoreButtonLabel": "Learn more"
     }
    });
    
  2. ./src/webparts/greeting/loc/nl-nl.js ファイルを開き、次に示すようにコードを変更します。Next, open the ./src/webparts/greeting/loc/nl-nl.js file and change its code to:

    define([], function() {
     return {
       "PropertyPaneDescription": "Instellingen van het begroeting webonderdeel",
       "DisplayGroupName": "Weergave",
       "GreetingFieldLabel": "Begroeting die in het webonderdeel getoond wordt",
       "LearnMoreButtonLabel": "Meer informatie"
     }
    });
    
  3. 次のコマンドを実行して、翻訳後の文字列が正しく表示されることを確認します。Confirm that the translated string is correctly displayed by running the following command:

    gulp serve --locale=nl-nl
    


    [詳細] ボタンのラベルが、既定の英語 (米国) ではなくオランダ語 (オランダ) で表示される

擬似ロケールを使用して Web パーツのグローバル化とローカライズを改善するImprove globalizing and localizing web parts using pseudo-locales

Web パーツの作成時にローカライズを使用することには明らかなメリットがありますが、それは開発者が見過ごしやすい点でもあります。Using localization when building web parts offers clear benefits but is also something that developers overlook easily. 多くの場合、他のロケールへの翻訳はプロジェクトの後半で提供されるため、すべてのコードが別のロケールを適切にサポートすることを確認するのはテスターには困難です。Using localization when building web parts offers clear benefits but is also something that developers overlook easily. Often, translations to other locales are provided later in the project and it's hard for testers to verify that all code will properly support the different locales.

同じ単語でも、別のロケールでは長さが異なります。The same words in different locales have different lengths. たとえば、英語からドイツ語やオランダ語に翻訳した場合、同じ文でも 35% 長くなる場合があります。For example, the same sentence translated from English to German or Dutch can become 35% longer. 事前にすべての翻訳が利用できない場合、開発者およびデザイナーにとって、ユーザー インターフェイスに長い文字列が収まるかどうかを確認するのは困難です。Without all translations available upfront, it's difficult for developers and designers to ensure that the user interface can properly accommodate longer strings.

一部の言語では、標準の ASCII 文字セット以外の特殊文字を使用します。デザイナーが標準フォント以外のフォントを使用する場合、フォントでいくつかの特殊文字が正しくサポートされない場合があります。Some languages use special characters beyond the standard ASCII character set. If designers use a non-standard font, it is possible that the font doesn't properly support some special characters.

プロジェクトの後半でこれらのすべての問題に気付いた場合、遅延が発生し、修正プログラムにコストがかかる可能性があります。SharePoint Framework では、開発者が Web パーツの作成中に擬似ロケールを使用して、これらの問題に対処できるようになっています。Finding out about all these issues late in the project will likely lead to delays and costly fixes. The SharePoint Framework allows developers to use pseudo-locales to address these issues while building web parts.

ヒント

擬似ロケールとはWhat are pseudo-locales? 擬似ロケールとは、特殊文字、右から左方向の言語、または長い文字列をユーザー インターフェイスに収める対応など、ローカライズ プロセスのさまざまな側面をソフトウェアが適切にサポートしているかどうかをテストするためのロケールです。Pseudo-locales are locales designed to test software for proper support of the different aspects of the localization process such as support for special characters, right-to-left languages, or accommodating longer strings in the user interface.

基本の擬似ロケールを追加するAdd the base pseudo-locale

  1. ./src/webparts/greeting/loc フォルダーで、qps-ploc.js という新しいファイルを追加し、次のコードを貼り付けます。In the ./src/webparts/greeting/loc folder, add a new file named qps-ploc.js and paste the following code:

    define([], function() {
     return {
       "PropertyPaneDescription": "[!!! Gřèèƭïñϱ ωèβ ƥářƭ çôñƒïϱúřáƭïôñ ℓôřè₥ ïƥƨú !!!]",
       "DisplayGroupName": "[!!! Ðïƨƥℓᥠℓ !!!]",
       "GreetingFieldLabel": "[!!! Gřèèƭïñϱ ƭô ƨλôω ïñ ƭλè ωèβ ƥářƭ ℓôřè₥ ïƥƨú !!!]",
       "LearnMoreButtonLabel": "[!!! £èářñ ₥ôřè ℓôř !!!]"
     }
    });
    

    ヒント

    Pseudolocalize! で、米国 (英語) の文字列を基本の擬似ロケールの同等物に変換できます。You can convert US English strings to their base pseudo-locale equivalent at Pseudolocalize!. 生成された文字列の長さを 35% 増やすことで、ドイツ語やオランダ語などの長いロケールに翻訳された文字列の長さをシミュレートすることができます。Tip: you can convert US English strings to their base pseudo-locale equivalent at http://www.pseudolocalize.com. By increasing the length of the generated string with 35% you should be able to simulate the length of strings translated to longer locales such as German or Dutch. さらに、翻訳を角かっこと感嘆符で囲むことで、画面に文字列全体が表示されるかどうかがより簡単にわかります。Additionally, by surrounding the translations with brackets and exclamation marks you can more easily see if the whole string is displayed on the screen.

  2. 次のコマンドを実行して、基本の擬似ロケールを使用してプロジェクトをテストします。Test the project using the base pseudo-locale by running the following command:

    gulp serve --locale=qps-ploc
    

    Web パーツをページに追加すると、Web パーツの本体に国際化されていない 2 つの文字列があり、基本の擬似ロケールではなく英語 (米国) のまま表示されていることにすぐ気付くはずです。After adding the web part to the page, you can quickly see that there are two strings in the web part body that have not been internationalized and are still displayed in US English rather than in the base pseudo-locale.

    基本の擬似ロケールを使用してテストしているにもかかわらず、Web パーツの本体で 2 つの文字列が英語 (米国) で表示される

  3. Web パーツのプロパティ ウィンドウを開いて、すべての文字列と特殊文字が正しく表示されていること、およびそれらが使用可能なスペースに正しく収まっていることを確認します。If you open the web part property pane, you can confirm that all strings and their special characters are displayed properly and that they fit in the available space correctly.

    基本の擬似ロケールを使用してローカル ワークベンチで Web パーツをテストすると、Web パーツのプロパティ ウィンドウが開く

Web パーツの設定値をローカライズするLocalize web part settings values

SharePoint は、サイトの管理者がユーザー インターフェイス用に複数の言語を有効にするための多言語ユーザー インターフェイス (MUI) をサポートしています。Microsoft SharePoint supports Multilingual User Interface (MUI) where the site administrator can enable multiple languages for the user interface. When the user visits the site, its UI will automatically be displayed using the preferred language based on that user's preferences. ユーザーがサイトを訪問すると、ユーザー設定に基づいて UI が優先言語で自動的に表示されます。Microsoft SharePoint supports Multilingual User Interface (MUI) where the site administrator can enable multiple languages for the user interface. When the user visits the site, its UI will automatically be displayed using the preferred language based on that user's preferences.

多言語のサイトで使用されている Web パーツは、現在使用されている言語を自動的に検出し、その内容をその言語で表示します。Web parts used on multilingual sites should automatically detect the currently used language and display their contents in that language. SharePoint Framework は、現在使用されている言語に対応するリソース ファイルを自動的に読み込むことによってこのプロセスを簡略化します。The SharePoint Framework simplifies this process by automatically loading the resource file corresponding to the currently used language. さらに、ホストされたバージョンの SharePoint ワークベンチを使用して SharePoint Framework の Web パーツをテストする場合も、ワークベンチはユーザーの優先言語を自動的に使用します。Additionally, when testing SharePoint Framework web parts using the hosted version of the SharePoint Workbench, the Workbench also automatically uses the language preferred by the user.

Web パーツ プロパティで構成された値はリソース ファイルに格納されません。Values configured through web part properties are not stored in resource files. 既定では、構成済みの値はそのまま使用されるため、ユーザーの優先言語がオランダ語であっても、ユーザーへの案内応答が英語で表示されるといった矛盾が生じる場合があります。Values configured through web part properties are not stored in resource files. By default, the configured value is used as-is, which might lead to inconsistencies such as greeting the user in English when the user's preferred language is Dutch.

オランダ語 (オランダ) を使用するようにワークベンチが設定されているにもかかわらず、案内応答メッセージが英語 (米国) で表示される


SharePoint Framework で提供される構成要素を使用すると、Web パーツの構成値を複数の言語で格納するよう Web パーツを拡張できます。Using the building blocks provided with the SharePoint Framework, you can extend your web part with support for storing web part configuration values in multiple languages. For each of the supported languages the property pane will display a separate text field in which the user can enter the translated value for that property. サポートされている言語ごとに別々のテキスト フィールドがプロパティ ウィンドウに表示され、ユーザーは翻訳したそのプロパティの値を入力できます。Using the building blocks provided with the SharePoint Framework, you can extend your web part with support for storing web part configuration values in multiple languages. For each of the supported languages the property pane will display a separate text field in which the user can enter the translated value for that property.

複数のテキスト フィールドが Web パーツのプロパティ ウィンドウに表示され、Web パーツの値を翻訳できる

注意

この記事に示されている Web パーツのテストに使用する SharePoint サイトは、英語 (米国)、オランダ語、ドイツ語が有効な多言語サイトです。The SharePoint site used to test the web part shown in this article is a multilingual site with the US English, Dutch, and German languages enabled. SharePoint サイトで他の言語を有効にする方法については、「サイトのユーザー インターフェイスで使用できるようにする言語の選択」を参照してください。For more information about enabling additional languages in SharePoint sites see the Choose the languages you want to make available for a site’s user interface support article.

SharePoint Online でサポートされる言語のリストを追加するAdd list of languages supported by SharePoint Online

多言語の SharePoint サイトで有効にされた言語の一覧は、ロケール識別子 (LCID) の配列として返されます。たとえば、英語 (米国) の場合は 1033 になります。The list of languages enabled on a multilingual SharePoint site is returned as an array of locale identifiers (LCID).

ただし、現在使用されている言語は文字列として返されます。たとえば、英語 (米国) の場合は en-US になります。However, the currently used language is returned as a string, for example, en-US for US English. JavaScript には LCID 番号をロケールの名前に変換する、またはその逆を行うためのネイティブな方法がないため、それを自分で行う必要があります。As JavaScript doesn't have a native way of converting the LCID number to the locale name, and vice-versa, you have to do it yourself.

  1. コード エディターで、./src/webparts/greeting/GreetingWebPart.ts ファイルを開きます。In the code editor, open the ./src/webparts/greeting/GreetingWebPart.ts file, and add a new class variable named supportedLanguageIds:

  2. 次のコードにより、既存の GreetingWebPart 内部に locales という名前の新しいクラス変数を追加します。In the code editor, open the ./src/webparts/greeting/GreetingWebPart.ts file and add a new class variable named locales inside of existing GreetingWebPart with the following code:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
     private locales = {
       1025: 'ar-SA',
       1026: 'bg-BG',
       1027: 'ca-ES',
       1028: 'zh-TW',
       1029: 'cs-CZ',
       1030: 'da-DK',
       1031: 'de-DE',
       1032: 'el-GR',
       1033: 'en-US',
       1035: 'fi-FI',
       1036: 'fr-FR',
       1037: 'he-IL',
       1038: 'hu-HU',
       1040: 'it-IT',
       1041: 'ja-JP',
       1042: 'ko-KR',
       1043: 'nl-NL',
       1044: 'nb-NO',
       1045: 'pl-PL',
       1046: 'pt-BR',
       1048: 'ro-RO',
       1049: 'ru-RU',
       1050: 'hr-HR',
       1051: 'sk-SK',
       1053: 'sv-SE',
       1054: 'th-TH',
       1055: 'tr-TR',
       1057: 'id-ID',
       1058: 'uk-UA',
       1060: 'sl-SI',
       1061: 'et-EE',
       1062: 'lv-LV',
       1063: 'lt-LT',
       1066: 'vi-VN',
       1068: 'az-Latn-AZ',
       1069: 'eu-ES',
       1071: 'mk-MK',
       1081: 'hi-IN',
       1086: 'ms-MY',
       1087: 'kk-KZ',
       1106: 'cy-GB',
       1110: 'gl-ES',
       1164: 'prs-AF',
       2052: 'zh-CN',
       2070: 'pt-PT',
       2074: 'sr-Latn-CS',
       2108: 'ga-IE',
       3082: 'es-ES',
       5146: 'bs-Latn-BA',
       9242: 'sr-Latn-RS',
       10266: 'sr-Cyrl-RS',
     };
    
     // ...
    }
    

    locales 変数は、SharePoint Online でサポートされているすべての言語を一覧表示します。The locales variable lists all languages supported by SharePoint Online.

  3. ロケール名から LCID を取得したり、LCID からロケール名を取得したりできるように 2 つのクラス メソッドを追加します。Next, add two class methods that will allow you to get the LCID from the locale name, and the locale name from the LCID:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
     // ...
    
     private getLocaleId(localeName: string): number {
       const pos: number = (Object as any).values(this.locales).indexOf(localeName);
       if (pos > -1) {
         return parseInt(Object.keys(this.locales)[pos]);
       }
       else {
         return 0;
       }
     }
    
     private getLocaleName(localeId: number): string {
       const pos: number = Object.keys(this.locales).indexOf(localeId.toString());
       if (pos > -1) {
         return (Object as any).values(this.locales)[pos];
       }
       else {
         return '';
       }
     }
    }
    

標準の greeting Web パーツ プロパティを削除するRemove the standard greeting web part property

もともと、Greeting Web パーツには greeting プロパティが定義されており、ユーザーは画面に表示される案内応答を指定することができました。Originally, the Greeting web part had the greeting property defined where the user could specify the greeting to be displayed on the screen. 多言語の SharePoint サイトをサポートするように Web パーツを適合させるには、複数の値、つまり言語ごとに 1 つの値を格納する必要があります。To adapt the web part to support multilingual SharePoint sites, you need to store multiple values; one for each language. サイトで有効にされる言語は事前にはわからないため、1 つの静的な Web パーツのプロパティを使用するのではなく、実行時に Web パーツのプロパティを動的に生成することができます。Because you cannot know up front which languages will be enabled on the site, rather than using one static web part property, you will dynamically generate web part properties at runtime.

  1. コード エディターで、./src/webparts/greeting/GreetingWebPart.manifest.json ファイルを開きます。In the code editor open the ./src/webparts/greeting/GreetingWebPart.manifest.json file.

  2. properties プロパティから、greeting プロパティを削除します。Remove the greeting property from the properties property:

    {
     // ...
    
     "preconfiguredEntries": [{
       "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Other
       "group": { "default": "Other", "nl-nl": "Anders" },
       "title": { "default": "Greeting", "nl-nl": "Begroeting" },
       "description": { "default": "Greets the user", "nl-nl": "Begroet de gebruiker" },
       "officeFabricIconFontName": "Page",
       "properties": {
       }
     }]
    }
    
  3. ./src/webparts/greeting/GreetingWebPart.ts ファイルを開きます。Open the ./src/webparts/greeting/GreetingWebPart.ts file.

  4. IGreetingWebPartProps インターフェイス定義から、greeting プロパティを削除します。Remove the **** property from the IGreetingWebPartProps interface.

    export interface IGreetingWebPartProps {
    }
    
  5. React の主要コンポーネントに案内応答が表示されるので、./src/webparts/greeting/components/IGreetingProps.ts ファイルを開き、IGreetingProps インターフェイスを次のように変更します。Because the main React component should display a greeting, open the ./src/webparts/greeting/components/IGreetingProps.ts file, and change the IGreetingProps interface to:

    export interface IGreetingProps {
     greeting: string;
    }
    

    この変更によって、表示される案内応答を Web パーツから React コンポーネントに渡すことができます。With this modification, you can pass the greeting to be displayed from the web part to the React component.

有効になっているすべての言語のプロパティ ウィンドウのテキスト フィールドを表示するDisplay property pane text fields for all enabled languages

最初に、ユーザーは Web パーツの構成を使用してウェルカム メッセージを設定することができました。Initially, by using the web part configuration, the user could configure a welcome message. Web パーツによってユーザーは、言語設定に関係なく、すべてのユーザーに表示される 1 つの値を設定できました。The web part allowed the user to configure a single value that was displayed to all users no matter what their language preference was. 現在のサイトで有効になっている言語の一覧を取得すれば、サイトで有効になっているすべての言語の翻訳をユーザーが指定するためのテキスト フィールドを動的に表示できます。By retrieving the list of languages enabled on the current site, you can dynamically display text fields to allow the user to provide translations for all the languages enabled on the site.

現在のサイトで有効になっている言語に関する情報を読み込むLoad information about languages enabled in the current site

最初の手順は、現在のサイトで有効になっているすべての言語に関する情報を読み込むことです。The first step is to load the information about all languages enabled in the current site.

  1. コード エディターで、./src/webparts/greeting/GreetingWebPart.ts ファイルを開きます。In the code editor, open the ./src/webparts/greeting/GreetingWebPart.ts file, and add a new class variable named supportedLanguageIds:

  2. supportedLanguageIds という名前の新しいクラス変数を追加します。Add a new class variable named itemsDropdownDisabled.

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
     // ...
     private supportedLanguageIds: number[];
     // ...
    }
    

    SharePoint 内のデータを照会するため、SharePoint HTTP クライアントを使用します。Since we will be querying data in SharePoint, we will be using SharePoint Http Client for the operations.

  3. GreetingWebPart の直前に次の import を追加します。Add following imports just above the GreetingWebPart.

    import {
     SPHttpClient,
     SPHttpClientResponse
    } from '@microsoft/sp-http';
    
  4. GreetingWebPart クラスに、getSupportedLanguageIds という名前の新しいメソッドを追加します。Next, in the GreetingWebPart class, add a new method named getSupportedLanguageIds:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
     // ...
    
     private getSupportedLanguageIds(): Promise<number[]> {
       return new Promise<number[]>((resolve: (supportedLanguageIds: number[]) => void, reject: (error: any) => void): void => {
         if (this.supportedLanguageIds) {
           resolve(this.supportedLanguageIds);
           return;
         }
    
         this.context.spHttpClient.get(this.context.pageContext.web.absoluteUrl + '/_api/web?$select=SupportedUILanguageIds', SPHttpClient.configurations.v1)
         .then((response: SPHttpClientResponse): Promise<{ SupportedUILanguageIds: number[] }> => {
           return response.json();
         }).then((siteInfo: { SupportedUILanguageIds: number[] }): void => {
           this.supportedLanguageIds = siteInfo.SupportedUILanguageIds;
           resolve(siteInfo.SupportedUILanguageIds);
         }, (error: any): void => {
           reject(error);
         });
       });
     }
    }
    

現在のサイトで有効になっている言語の一覧は、1 回だけ読み込む必要があります。The list of languages enabled on the current site should be loaded only once. 言語に関する情報がまだ読み込まれていない場合、メソッドは標準の SharePoint Framework の HTTP クライアントを使用して SharePoint REST API を呼び出し、現在のサイトで有効になっている言語に関する情報を取得します。The list of languages enabled in the current site should be loaded only once. If the information about the languages hasn't been loaded yet, the method uses the standard SharePoint Framework HTTP Client to call the SharePoint REST API and retrieve the information about languages enabled on the current site.

すべての言語用のテキスト フィールドを動的に表示するDynamically render text fields for all languages

現在のサイトで有効になっている言語に関する情報を取得できたら、案内応答メッセージの翻訳済みの値をユーザーが指定できるように、これらの各言語でテキスト フィールドを表示します。Now that you can retrieve the information about the languages enabled on the current site, you will display text fields for each of these languages so that the user can specify translated values for the greeting message.

  1. コード エディターで、./src/webparts/greeting/GreetingWebPart.ts ファイルを開きます。In the code editor, open the ./src/webparts/greeting/GreetingWebPart.ts file, and add a new class variable named supportedLanguageIds:

  2. greetingFields という名前の新しいクラス変数を GreetingWebPart クラスに追加します。In the code editor, open the ./src/webparts/greeting/GreetingWebPart.ts file, and add a new class variable named greetingFields to the GreetingWebPart class:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
     // ...
     private greetingFields: IPropertyPaneField<any>[] = [];
     // ...
    }
    
  3. @microsoft/sp-webpart-base パッケージの import ステートメントを次のように変更します。Change the import statement for the @microsoft/sp-webpart-base package to:

    import {
     BaseClientSideWebPart,
     IPropertyPaneConfiguration,
     PropertyPaneTextField,
     IPropertyPaneField
    } from '@microsoft/sp-webpart-base';
    
  4. propertyPaneSettings ゲッターを変更し、新たに追加された greetingFields クラス変数からテキスト フィールドの一覧を取得します。Change the propertyPaneSettings getter to get the list of text fields from the newly added greetingFields class variable:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
     // ...
    
       protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
       return {
         pages: [
           {
             header: {
               description: strings.PropertyPaneDescription
             },
             groups: [
               {
                 groupName: strings.GreetingGroupName,
                 groupFields: this.greetingFields
               }
             ]
           }
         ]
       };
     }
    
     // ...
    }
    

    サイトで複数の言語が有効になっている場合、Web パーツは、ユーザーが案内応答メッセージを入力するために複数のフィールドを表示します。If the site has multiple languages enabled, the web part will render multiple fields for the user to enter the greeting message. これらのフィールドが同類であることがはっきりわかるように、それらを別個のグループに配置します。To make it clear that these fields belong together, put them in a separate group.

  5. コード エディターで ./src/webparts/greeting/loc/mystrings.d.ts ファイルを開き、次に示すようにコードを変更します。In the code editor, open the ./src/webparts/greeting/loc/mystrings.d.ts file, and change its code to:

    declare interface IGreetingWebPartStrings {
     PropertyPaneDescription: string;
     GreetingGroupName: string;
     LearnMoreButtonLabel: string;
    }
    
    declare module 'GreetingWebPartStrings' {
     const strings: IGreetingWebPartStrings;
     export = strings;
    }
    
  6. これに応じてリソース ファイルを更新し、GreetingGroupName 文字列の値を指定します。Update the resource files accordingly to provide values for the GreetingGroupName string.

    ./src/webparts/greeting/loc/en-us.js./src/webparts/greeting/loc/en-us.js:

    define([], function() {
     return {
       "PropertyPaneDescription": "Greeting web part configuration",
       "GreetingGroupName": "Greeting to show in the web part",
       "LearnMoreButtonLabel": "Learn more"
     }
    });
    

    ./src/webparts/greeting/loc/nl-nl.js./src/webparts/greeting/loc/nl-nl.js:

    define([], function() {
     return {
       "PropertyPaneDescription": "Instellingen van het begroeting webonderdeel",
       "GreetingGroupName": "Begroeting die in het webonderdeel getoond wordt",
       "LearnMoreButtonLabel": "Meer informatie"
     }
    });
    

    ./src/webparts/greeting/loc/qps-ploc.js./src/webparts/greeting/loc/qps-ploc.js:

    define([], function() {
     return {
       "PropertyPaneDescription": "[!!! Gřèèƭïñϱ ωèβ ƥářƭ çôñƒïϱúřáƭïôñ ℓôřè₥ ïƥƨú !!!]",
       "GreetingGroupName": "[!!! Gřèèƭïñϱ ƭô ƨλôω ïñ ƭλè ωèβ ƥářƭ ℓôřè₥ ïƥƨú !!!]",
       "LearnMoreButtonLabel": "[!!! £èářñ ₥ôřè ℓôř !!!]"
     }
    });
    
  7. ./src/webparts/greeting/GreetingWebPart.ts ファイルで、次のコードを使用して onPropertyPaneConfigurationStart メソッドを上書きします。In the ./src/webparts/greeting/GreetingWebPart.ts file override the onPropertyPaneConfigurationStart method using the code:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
     // ...
     protected onPropertyPaneConfigurationStart(): void {
       this.context.statusRenderer.displayLoadingIndicator(this.domElement, 'languages');
    
       this.getSupportedLanguageIds()
         .then((supportedLanguageIds: number[]): void => {
           this.greetingFields = [];
           supportedLanguageIds.forEach(localeId => {
             this.greetingFields.push(PropertyPaneTextField(`greeting_${localeId}`, {
               label: this.getLocaleName(localeId)
             }));
           });
    
           this.context.propertyPane.refresh();
           this.context.statusRenderer.clearLoadingIndicator(this.domElement);
           this.render();
         });
     }
    }
    

    ユーザーが Web パーツのプロパティ ウィンドウを開くと、メソッドは現在のサイトで有効になっている言語に関する情報を読み込みます。When the user opens the web part property pane, the method will load the information about the languages enabled in the current site. この情報の読み込みには時間がかかる場合があるため、メソッドには、ユーザーにその状態を通知する読み込みインジケーターが表示されます。Because loading this information might take a moment, the method displays a loading indicator communicating its status to the user.

    有効にされた言語についての情報が読み込まれると、メソッドは新しいプロパティ ウィンドウのテキスト フィールドを作成します。これは、greeting__lcid_ という名前の動的な Web パーツ プロパティにリンクされています。たとえば、英語 (米国) の場合は greeting_1033 になります。Once the information about the enabled languages is loaded, the method creates a new property pane text field linked to a dynamic web part property named greeting__lcid_.

    有効になっているすべての言語のテキスト フィールドが構築された後、メソッドは IPropertyPaneAccessor.refresh メソッドを呼び出してプロパティ ウィンドウを更新します。Once text fields for all enabled languages are constructed, the method refreshes the property pane by calling the IPropertyPaneAccessor.refresh method.

    最後に、メソッドは Web パーツ読み込みインジケーターをクリアし、Web パーツの本体を再表示します。Finally, the method clears the web part loading indicator and re-renders the web part body.

    有効になっているすべての言語のテキスト フィールドが Web パーツのプロパティ ウィンドウに表示される

ユーザーの優先言語で案内応答を表示するShow the greeting for the preferred user language

もともと Web パーツは、ユーザーの優先言語にかかわらず、すべてのユーザーに同じ案内応答を表示していました。Originally, the web part showed the same greeting for all users no matter what their preferred language was. さまざまな翻訳のウェルカム メッセージが Web パーツに保存されたので、現在のユーザーの優先言語を使用する案内応答を表示するようにします。Originally the web part showed the same greeting for all users no matter their preferred language. Now that the web part has different translations of the welcome message stored, it should display the greeting using the language preferred by the current user.

  1. ./src/webparts/greeting/GreetingWebPart.ts ファイルで、Web パーツの render メソッドを次のように変更します。In the ./src/webparts/greeting/GreetingWebPart.ts file, change the web part's render method to:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
     // ...
    
     public render(): void {
       const element: React.ReactElement<IGreetingProps> = React.createElement(Greeting, {
         greeting: this.getGreeting()
       });
    
       ReactDom.render(element, this.domElement);
     }
    }
    
  2. GreetingWebPart に、getGreeting という名前の新しいメソッドを追加します。Next, in the GreetingWebPart add a new method named getGreeting:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
     // ...
    
     private getGreeting(): string {
       let localeId: number = this.getLocaleId(this.context.pageContext.cultureInfo.currentUICultureName);
       if (localeId === 0) {
         localeId = 1033;
       }
    
       return this.properties[`greeting_${localeId}`];
     }
    
     // ...
    }
    

    このメソッドは、現在使用されている言語を取得し、ロケール ID に変換します。This method gets the currently used language and converts it to a locale ID. Then it returns the value of the greeting property translated to that language. 次に、その言語に翻訳されている greeting プロパティの値を返します。It then returns the value of the greeting property translated to that language.

各種ビルドのローカライズLocalization in different build types

選択したビルド モードに応じて、SharePoint Framework はローカライズ ファイルを異なる方法で処理します。Depending on the selected build mode, the SharePoint Framework handles localization files differently. Following are some of the differences between the files generated in a debug and a release build. デバッグ ビルドとリリース ビルドで生成されたファイルの相違点の一部を次に示します。Depending on the selected build mode, the SharePoint Framework handles localization files differently. Following are some of the differences between the files generated in a debug and a release build.

デバッグ ビルドのローカライズ ファイルLocalization files in the debug build

SharePoint Framework プロジェクトをデバッグ モードでビルドする場合、生成された Web パーツのマニフェストには既定のロケールに関する情報のみが含まれます。When building SharePoint Framework projects in debug mode, only the information about the default locale is included in the generated web part manifest. デバッグ モードでは、SharePoint Framework は、既定の en-US ロケール、プロジェクトの構成で指定されたロケール、またはコマンド ラインの locale 引数で指定されたロケールのいずれかを使用します。In debug mode SharePoint Framework either uses the default en-US locale or the locale that has been specified in the project configuration or using the locale argument in command line.

翻訳された文字列が記載されたリソース ファイルは、出力 dist フォルダーに含まれていません。Resource files with translated strings are not included in the output dist folder. 代わりに、生成された Web パーツのマニフェスト内のパスを使用して、中間 lib フォルダーから実行時に読み込まれます。Instead they are loaded at runtime from the intermediate lib folder using the path in the generated web part manifest.

デバッグ ビルド中に生成された Web パーツのマニフェストにある GreetingWebPartStrings モジュールに関する情報を参照すれば、Web パーツでさまざまなロケール (en-US、nl-NL、qps-ploc) がサポートされているとしても、中間的な場所に格納されている en-us (英語) リソース ファイルへのパスがローカライズ モジュールの既定のパスとして割り当てられていることがわかります。Looking at the information about the GreetingWebPartStrings module in the web part manifest generated during a debug build, you can see that despite the different locales supported by the web part (en-US, nl-NL and qps-ploc) the path to the en-US resource file stored in the intermediate location has been assigned as the default path of the localization module.

{
  "id": "edbc4e31-6085-4ffa-85f4-eeffcb0ea2d4",
  "alias": "GreetingWebPart",
  "componentType": "WebPart",
  "version": "0.0.1",
  "manifestVersion": 2,
  // ...
  "loaderConfig": {
    "entryModuleId": "greeting-web-part",
    "internalModuleBaseUrls": [
      "https://localhost:4321/"
    ],
    "scriptResources": {
      "greeting-web-part": {
        "type": "path",
        "path": "dist/greeting-web-part.js"
      },
      "GreetingWebPartStrings": {
        "defaultPath": "lib/webparts/greeting/loc/en-us.js",
        "type": "localizedPath",
        "paths": {
          "en-US": "lib/webparts/greeting/loc/en-us.js",
          "nl-NL": "lib/webparts/greeting/loc/nl-nl.js",
          "qps-ploc": "lib/webparts/greeting/loc/qps-ploc.js"
        }
      },
      // ...
    }
  }
}

リリース ビルドのローカライズ ファイルLocalization files in the release build

SharePoint フレームワーク プロジェクトをリリース モードでビルドする場合、生成された Web パーツのマニフェストには使用可能なすべてのロケールに関する情報が含まれます。When building SharePoint Framework projects in release mode, the information about all available locales is included in the generated web part manifest. また、各ロケールのリソースは、別々のファイルに格納されます。Additionally, resources for each locale are stored in a separate file. これらのリソース ファイルは、Web パーツのマニフェストおよび Web パーツのバンドルとともに ./temp/deploy フォルダーにコピーされます。These resource files are copied, along with the web part manifest and the web part bundle to the ./temp/deploy folder.

重要

リリース ビルドでは、リソース ファイルは ./dist フォルダーではなく、./temp/deploy フォルダーだけにコピーされます。Important: In release builds resource files are copied only to the ./temp/deploy folder and not to the ./dist folder. Web パーツを運用環境に展開する場合、ファイルは常に ./temp/deploy フォルダーから使用し、Web パーツに必要なすべてのファイルが確実に展開されるようにする必要があります。When deploying your web part to production you should always use files from the ./temp/deploy folder to ensure that you are deploying all files required by your web part.

リリース ビルドで生成された最新の Web マニフェストを調べると、サポートされるすべてのロケールへの参照が GreetingWebPartStrings モジュールに含まれていることがわかります。Examining the latest web part manifest generated in a release build, you can see that now the GreetingWebPartStrings module contains references to all supported locales.

{
  "id": "edbc4e31-6085-4ffa-85f4-eeffcb0ea2d4",
  "alias": "GreetingWebPart",
  "componentType": "WebPart",
  "version": "0.0.1",
  "manifestVersion": 2,
  // ...
  "loaderConfig": {
    "entryModuleId": "greeting-web-part",
    "internalModuleBaseUrls": [
      "https://cdn.contoso.com/"
    ],
    "scriptResources": {
      "greeting-web-part": {
        "type": "path",
        "path": "greeting-web-part_159d9eb591c6716cae6d0ff15b78a19a.js"
      },
      "GreetingWebPartStrings": {
        "defaultPath": "react-localization-greetingwebpartstrings_en-us_b5e89eba6e8d819bf1647b3ab505dae5.js",
        "type": "localizedPath",
        "paths": {
          "en-US": "react-localization-greetingwebpartstrings_en-us_b5e89eba6e8d819bf1647b3ab505dae5.js",
          "nl-NL": "react-localization-greetingwebpartstrings_nl-nl_d6e80ff75385975e7737774e0802641e.js",
          "qps-ploc": "react-localization-greetingwebpartstrings_qps-ploc_effe5ee4af9cadee91bbf84327eb7308.js"
        }
      },
      // ...
    }
  }
}

Web パーツをページ上に読み込むと、SharePoint Framework はコンテキスト サイトからの情報を使用して、対応するロケールのリソース ファイルを自動的に読み込みます。When loading the web part on the page, the SharePoint Framework will automatically load the resource file for the corresponding locale by using the information from the context site. 一致するリソース ファイルが見つからない場合、SharePoint Framework は defaultPath プロパティで指定されたファイルを読み込みます。If no matching resource file is found, the SharePoint Framework will load the file specified in the defaultPath property.

SharePoint Framework は、リソース ファイルを分けることにより、サイトで使用されるロケールと一致する最小限の量のデータだけをページに読み込みます。By keeping the resource files separate, the SharePoint Framework minimizes the amount of data loaded on the page to the locale that matches the one used in the site.

関連項目See also