.XCSTRINGS - Apple Strings Catalog (Strings)

文本由 Phrase Language AI 从英语机器翻译而得。

文件扩展名	.xcstrings
API 扩展	strings_catalog
导入	是
导出	是
复数形式支持	是
描述支持	是
格式选项这些选项可以在文件上传和/或下载时指定。根据上传/下载方法（API、CLI、Repo同步等），它们可以在查询参数`上传`、`下载`或在`phrase.yml`配置文件中指定。	convert_placeholder default_extraction_state

Apple Strings Catalog (.xcstrings) 是在 Xcode 15 中引入的本地化格式。它增强了开发人员管理本地化字符串的方式，支持处理复数、设备特定变体等的结构化格式。这种格式正成为管理 iOS 和 macOS 应用程序本地化的推荐方法。

备注、提取状态 和 是否翻译 元数据字段按要求的顺序导入和导出，以确保与 Xcode 的兼容性。

Phrase 还在导入时将 Xcode 翻译状态映射到最接近的 Strings 等效项，并在导出时将其转换回与 Xcode 兼容的值。如果没有特定的映射适用，翻译将作为默认导出值。如有需要，请使用导入时忽略翻译状态选项跳过状态映射。

代码示例

{
  "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 配置文件中仅指定一个文件目标。
使用 区域标识符 参数列出导出中包含的所有语言区域。

示例 .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 产品（s）已订购 的键对于 applewatch 设备被导入为名为 %lld 产品（s）已订购|==|device.applewatch 的复数键到 Phrase Strings 中。

在导出过程中，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 替换，作为名为 birdSightingAlert|==|substitution.BIRDS 的复数键导入到 Phrase Strings 中。

在导出过程中，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": "%@ 天"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ 天"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version":"1.0"
}

格式选项

标识符	convert_placeholder
类型	布尔值
上传	否
下载	是
默认	false
说明	占位符将被转换以匹配特定格式要求。示例：`$s`→`$@`，`%s`→`%@`

标识符	default_extraction_state
类型	字符串
上传	否
下载	是
默认	null
说明	定义在导出文件中写入键的 `extractionState` 值，当键上尚未定义提取状态时。如果一个键已经包含 `extractionState`，则在导出期间其值将被保留。支持： UI 下载 API CLI（通过 `.phrase.yml` 配置）和 Repo Sync