.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で導入されたローカリゼーションファイル形式です。これは、複数形、デバイス固有のバリエーションなどを処理するための構造化されたファイル形式をサポートすることで、開発者がStringsを管理する方法を強化します。このファイル形式は、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": "1.0"
}

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

CLI設定ファイルで訳文ファイルを1つだけ指定します。
locale_idsパラメータを使用して、エクスポートに含まれるすべての言語ロケールを一覧表示します。

Example .phrase.yml configuration

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ファイルをインポートする際、このセパレータを使用してデバイスタイプがベースキー名に追加されます。

例：

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

エクスポート中、Phrase Stringsはセパレーターを使用してデバイスのバリアントを検出し、Appleのローカライゼーションファイル形式用に元のネストされた構造を復元します。

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment": "Indicates the number of products ordered, with device-specific variations",
      "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ファイルから置換構造をインポートする

BIRDSの置換用のbirdSightingAlertという名前のキーは、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": "1.0"
}

ファイル形式オプション

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

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

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