.XCSTRINGS - Apple Strings Catalog (Strings)

本コンテンツはPhrase Language AIの機械翻訳により、英語から翻訳されています。

ファイル拡張子	.xcstrings
API拡張	strings_catalog
インポート	はい
エクスポート	はい
複数形のサポート	はい
説明のサポート	はい
フォーマットオプションこれらのオプションは、ファイルのアップロード時および／またはダウンロード時に指定できます。アップロード／ダウンロード方法（API、CLI、Repo syncなど）に応じて、クエリパラメータ`Upload`、`Download`、または`phrase.yml`設定ファイルで指定できます。	convert_placeholder default_extraction_state locale_code_mapping

Apple Strings Catalog (.xcstrings) は、Xcode 15で導入されたローカライゼーション形式です。これは、複数形、デバイス固有のバリエーションなどを処理するための構造化された形式をサポートすることで、開発者がローカライズされた文字列を管理する方法を強化します。この形式は、iOSおよびmacOSアプリケーションのローカライゼーションを管理するための推奨されるアプローチになりつつあります。

comment、extractionStateおよびshouldTranslateのメタデータフィールドは、Xcodeとの互換性を確保するために必要な順序でインポートおよびエクスポートされます。

Phraseは、インポート時にXcodeの翻訳状態を最も近いStringsの同等物にマッピングし、エクスポート時にXcode互換の値に変換し直します。特定のマッピングが適用されない場合、デフォルトのエクスポート値としてtranslatedが使用されます。必要に応じて、Ignore translation state on importオプションを使用して、状態のマッピングをスキップしてください。

コードサンプル

{
  "sourceLanguage": "en",
  "strings": {
    "Sync Warning": {
      "comment":"Sync function unavailable message",
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value":"Cloud Sync must be enabled to use this feature."
          
        },
        "fr": {
          "stringUnit": {
            "state": "translated",
            "value":"La synchronisation cloud doit être activée pour utiliser cette fonction."
          
        }
      }
    },
    "Chosen Collections": {
      "comment":"View title indicating selected photo collections",
      "localizations": {
        "fr": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld collection sélectionnée"
                
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld collections sélectionnées"
                
              }
            }
          }
        },
        "en": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld Collection Selected"
                
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld Collections Selected"
                
              }
            }
          }
        }
      }
    },
    "Settings Hub": {
      "localizations": {
        "es": {
          "stringUnit": {
            "state": "translated",
            "value":"Centro de configuración"
          
        }
      }
    }
  },
  "version":40

Phrase CLIを使用する場合、ファイルのエクスポートは.phrase.yml設定ファイルで定義された構造に従います。プル操作中に複数の言語を単一の.XCSTRINGSファイルにエクスポートするには、以下のようにします。

CLI設定ファイルでファイルターゲットを1つだけ指定してください。
locale_idsパラメータを使用して、エクスポートに含まれるすべての言語ロケールをリストします。

例 .phrase.yml 設定

pull:
  targets:
    - file: ./i18n-test/Localizable.xcstrings
      params:
        locale_id: en # Main language for the download
        locale_ids: # Additional languages to include
          - de
          - es
          - fr 
        file_format: strings_catalog

デバイスバリエーション

Apple Strings Catalogはデバイスバリエーションをサポートしており、使用されているAppleデバイスに応じて同じキーに対して異なる翻訳コンテンツを許可します。

Phrase Stringsでデバイスバリエーションを処理するために、セパレーター|==|を使用してデバイスごとに個別のキーが作成されます。.XCSTRINGSファイルをインポートする際、デバイスタイプはこのセパレーターを使用してベースキー名に追加されます。

例：

%lld Product(s) Orderedというキー（applewatchデバイス用）は、Phrase Stringsに%lld Product(s) Ordered|==|device.applewatchという複数形キーとしてインポートされます。

エクスポート中、Phrase Stringsはセパレーターを使用してデバイスバリアントを検出し、Appleのローカライズ形式に合わせて元のネスト構造を復元します。

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment":"注文された商品の数を示し、デバイス固有のバリエーションが存在する場合があります。"
      "localizations": {
        "en": {
          "variations": {
            "device": {
              "applewatch": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (Apple Watch)"
                      
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (Apple Watch)"
                      
                    }
                  }
                }
              },
              "ipad": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (iPad)"
                      
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (iPad)"
                      
                    }
                  }
                }
              },
              "iphone": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (iPhone)"
                      
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (iPhone)"
                      
                    }
                  }
                }
              },
              "mac": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (Mac)"
                      
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (Mac)"
                      
                    }
                  }
                }
              }
            }
          }
        },
        "fr": {
          "variations": {
            "plural": {
              "few": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produit(s) commandé(s)"
                
              },
              "many": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produits commandés"
                
              },
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produit commandé"
                
              }
            }
          }
        }
      }
    }
  }

文字列置換

Apple Strings Catalogは、動的コンテンツのための柔軟なプレースホルダーを提供する文字列置換をサポートしています。

Phrase Stringsで文字列置換を処理するには、セパレーター|==|を使用して個別のキーを作成します。.XCSTRINGSファイルをインポートする際、置換はこのセパレーターを使用してベースキー名に追加されます。

Phrase Stringsは、プロジェクト内で直接置換文字列を作成することもサポートしています。置換構造を手動で作成する場合、エクスポート時に正しいネスト形式が生成されるよう、ベースキーとそれに対応する置換キーを定義する必要があります。

置換には常に特定のキー命名形式が必要です：keyName|==|substitution.[specifier]。

例：既存の.XCSTRINGSファイルから置換構造をインポートする

birdSightingAlertというキー（BIRDS置換用）は、Phrase StringsにbirdSightingAlert|==|substitution.BIRDSという複数形キーとしてインポートされます。

エクスポート中、Phrase Stringsはセパレーターを使用して置換を検出し、Appleのローカライズ形式に合わせて元のネスト構造を復元します。

"birdSightingAlert": {
  "comment":"Alert message indicating the number of birds spotted",
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "new",
        "value":"You spotted %#@BIRDS@!"
      },
      "substitutions": {
        "BIRDS": {
          "formatSpecifier":"BIRDS",
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "new",
                  "value": "a bird"
                
              },
              "other": {
                "stringUnit": {
                  "state": "new",
                  "value": "several birds"
                
              },
              "zero": {
                "stringUnit": {
                  "state": "new",
                  "value": "no birds"
                
              }
            }
          }
        }
      }
    }

例：ゼロから置換文字列を作成する

ベースキー

keyNameというベースキーは、置換プレースホルダー%#@format@を含むトップレベルのフォーマット文字列を表します。

エクスポートされると、このキーはエントリのプライマリstringUnitとして書き込まれます：
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      
    }
  }
```

置換キー

置換文字列は、置換命名形式 keyName|==|substitution.li を使用して個別のキーとして定義されます。

このキーには、置換テキスト（通常は複数形のバリエーションを含む）が含まれます。エクスポート中、Phrase Stringsは |==|substitution. セパレーターを使用して置換を検出し、ベースキーの下にある対応するネストされた構造を復元します。

{
  "sourceLanguage": "en",
  "strings": {
    "keyName": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "%#@format@"
          },
          "substitutions": {
            "li": {
              "formatSpecifier": "li",
              "variations": {
                "plural": {
                  "one": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ day"
                    
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ days"
                    
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version":40

ファイル形式オプション

識別子	convert_placeholder
タイプ	ブール
アップロード	いいえ
ダウンロード	はい
デフォルト	false
概要	プレースホルダーは、形式固有の要件に合わせて変換されます。例：`$s`→`$@`、`%s`→`%@`

識別子	default_extraction_state
タイプ	文字列
アップロード	いいえ
ダウンロード	はい
デフォルト	null
概要	キーに抽出状態が定義されていない場合に、エクスポートされたファイルのキーに書き込まれる `extractionState` 値を定義します。キーに `extractionState` が既に含まれている場合、その値はエクスポート中も保持されます。対応環境： UIダウンロード API CLI（`.phrase.yml`設定経由）およびRepo Sync

識別子	locale_code_mapping
タイプ	オブジェクト
アップロード	はい
ダウンロード	はい
デフォルト
概要	Phraseのロケールコードを.XCSTRINGSファイルに書き込まれるロケールコードにマッピングします。各キーはPhraseのロケールコードであり、各値はファイルに書き込まれるコードです。例： { "en": "en-GB", "fr": "fr-FR" ダウンロード時に、Phraseは `sourceLanguage` フィールドと、マッピングキーに一致するすべての `localizations` キーを、マッピングされた値に書き換えます。マッピングのないコードは変更されません。アップロード時に、Phraseは同じマッピングを逆方向に適用し、ファイルロケールコードを対応するPhraseロケールコード（`sourceLanguage` を含む）に戻します。このオプションは、.XCSTRINGS ファイル自体から読み取られ、書き込まれるロケールコードにのみ影響します。Git統合のファイル命名パターンなどで使用されるファイル名ベースのロケールマッピングは、.XCSTRINGS 内のコードではなくファイルパスをマッピングする別の設定です。

iOS Strings (.strings) から Strings Catalog (.xcstrings) への移行

レガシーなiOS Strings形式 (.strings) は、翻訳コンテンツ内のリテラルのバックスラッシュ-nシーケンス (\\n) を実際の改行と同等として扱います。その結果、.strings形式の使用中に作成または編集された翻訳には、実際の改行文字の代わりにリテラルテキスト \\n が含まれる場合があります。

Strings Catalog (.xcstrings) はJSONベースの形式です。リテラルの \n シーケンスを含むコンテンツが .xcstrings にエクスポートされると、JSONエンコーディングはそのリテラルテキストをファイル内で \\n としてエスケープします。この動作は二重エスケープエラーではありません。これは、翻訳コンテンツ内に既に存在するリテラルの \n テキストを、正しいJSONエスケープを使用してエクスポートした結果です。

.strings から .xcstrings への移行後にこれを解決するには、影響を受けるコンテンツ内のリテラルの \n シーケンスを実際の改行に置き換えてください。

通常通りコンテンツをエクスポートします。
エクスポートしたファイルをテキストエディタで開きます。
リテラルの \n シーケンスのすべてのインスタンスを実際の改行に置き換えます。
ファイルを再インポートします。

アプリ内検索および置換機能は実際の改行の挿入をサポートしていないため、この置換はファイルを再インポートする前に外部のテキストエディタで実行する必要があります。