.XCSTRINGS - Apple Strings Catalog (Strings)

O conteúdo de toda a Central de Ajuda é traduzido automaticamente de inglês pelo Phrase Language AI.

Extensões de arquivo	.xcstrings
Extensão de API	strings_catalog
Importar	Sim
Exportar	Sim
Suporte para formas plurais	Sim
Suporte para descrição	Sim
Opções de formato Essas opções podem ser especificadas quando um arquivo é enviado e/ou baixado. Dependendo do método de upload/download (API, CLI, sincronização de repositório etc.), elas podem ser especificadas em parâmetros de consulta `Upload`, `Download` ou no arquivo de configuração `phrase.yml`.	convert_placeholder default_extraction_state

Apple Strings Catalog (.xcstrings) é um formato de localização introduzido no Xcode 15. Ele melhora a forma como os desenvolvedores gerenciam strings localizadas, suportando formatos estruturados para lidar com pluralização, variações específicas de dispositivos e mais. Esse formato está se tornando a abordagem recomendada para gerenciar localizações em aplicativos iOS e macOS.

Os campos de metadados comment, extractionState e shouldTranslate são importados e exportados na ordem necessária para garantir compatibilidade com o Xcode.

A Phrase também mapeia os estados de tradução do Xcode para os equivalentes mais próximos de Strings durante a importação e os converte de volta para valores compatíveis com o Xcode na exportação. Se nenhum mapeamento específico se aplicar, translated é usado como o valor de exportação padrão. Se necessário, use a opção Ignorar estado de tradução na importação para pular o mapeamento de estado.

Amostra de código

{
  "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"
}

Ao usar a Phrase CLI, as exportações de arquivos seguem a estrutura definida no arquivo de configuração .phrase.yml. Para garantir que múltiplas línguas sejam exportadas em um único arquivo .XCSTRINGS durante operações de pull:

Especifique apenas um alvo de arquivo no arquivo de configuração da CLI.
Use o parâmetro locale_ids para listar todos os locais de idioma incluídos na exportação.

Exemplo .phrase.yml configuração

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

Variações de dispositivo

O Apple Strings Catalog suporta variações de dispositivo, que permitem diferentes conteúdos de tradução para a mesma chave dependendo do dispositivo Apple que está sendo usado.

Para lidar com variações de dispositivo em Phrase Strings, chaves separadas são criadas para cada dispositivo usando o separador |==|. Ao importar arquivos .XCSTRINGS, o tipo de dispositivo é adicionado ao nome da chave base usando esse separador.

Exemplo

A chave chamada %lld Produto(s) Pedido(s) para o dispositivo applewatch é importada como uma chave plural chamada %lld Produto(s) Pedido(s)|==|device.applewatch no Phrase Strings.

Durante a exportação, o Phrase Strings detecta a variante do dispositivo usando o separador e restaura sua estrutura aninhada original para o formato de localização da Apple.

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment": "Indica o número de produtos pedidos, com variações específicas do dispositivo",
      "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é"
                }
              }
            }
          }
        }
      }
    }
  }
}

Substituições de string

O Apple Strings Catalog suporta substituições de string que fornecem marcadores de posição flexíveis para conteúdo dinâmico.

Para lidar com substituições de string no Phrase Strings, chaves separadas são criadas usando o separador |==|. Ao importar arquivos .XCSTRINGS, a substituição é adicionada ao nome da chave base usando este separador.

O Phrase Strings também suporta a criação de strings de substituição diretamente no projeto. Quando as estruturas de substituição são criadas manualmente, uma chave base e uma chave de substituição correspondente devem ser definidas para garantir que o formato aninhado correto seja gerado durante a exportação.

As substituições sempre requerem um formato de nomenclatura de chave específico: keyName|==|substitution.[specifier].

Exemplo: Importando estruturas de substituição de arquivos .XCSTRINGS existentes

A chave chamada birdSightingAlert para a substituição BIRDS é importada como uma chave plural chamada birdSightingAlert|==|substitution.BIRDS no Phrase Strings.

Durante a exportação, o Phrase Strings detecta a substituição usando o separador e restaura sua estrutura aninhada original para o formato de localização da 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"
                }
              }
            }
          }
        }
      }
    }
  }

Exemplo: Criando strings de substituição do zero

Chave base

Uma chave base chamada keyName representa a string de formato de nível superior que contém o marcador de posição de substituição %#@format@.

Quando exportada, esta chave é escrita como a stringUnit primária para a entrada:
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      }
    }
  }
}
```

Chave de substituição

Uma string de substituição é definida como uma chave separada usando o formato de nomenclatura de substituição: keyName|==|substitution.li.

Esta chave contém o texto de substituição, tipicamente com variações no plural. Durante a exportação, o Phrase Strings detecta a substituição usando o separador |==|substitution. e restaura a estrutura aninhada correspondente sob a chave base:

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

Opções de formato

Identificador	convert_placeholder
Tipo	Booleano
Upload	Não
Download	Sim
Padrão	false
Descrição	O marcador de posição será convertido para corresponder aos requisitos específicos de formato. Exemplo: `$s`→`$@`, `%s`→`%@`

Identificador	default_extraction_state
Tipo	string
Upload	Não
Download	Sim
Padrão	nulo
Descrição	Define o valor `extractionState` escrito nas chaves no arquivo exportado quando nenhum estado de extração já está definido na chave. Se uma chave já contém um `extractionState`, seu valor é preservado durante a exportação. Aceito em: downloads de UI API CLI (via configuração `.phrase.yml`) e Repo Sync