Visão geral
Marcas globais, companhias aéreas, eventos internacionais e cadeias de retalho emitem frequentemente passes de carteira para clientes em diferentes regiões linguísticas. A Passinstance disponibiliza um motor nativo de localização multilingue que compila strings e ativos localizados em:
-
Pacotes
.lprojda Apple Wallet: Dicionários padrão de strings Apple PassKit (<language>.lproj/pass.strings) empacotados diretamente no arquivo.pkpassjuntamente com imagens localizadas. -
Recursos
LocalizedStringda Google Wallet: Estruturas da API da Google Wallet com strings de fallback e traduções específicas por idioma (translatedValues[]).
Quando um cliente instala um passe, o iOS e o Android inspecionam automaticamente as definições de idioma e região do sistema operativo do utilizador, apresentando rótulos de campos, valores, notificações no ecrã bloqueado e gráficos da marca no respetivo idioma nativo — sem necessidade de criar modelos separados.
Arquitetura do sistema: Compilação multilingue PassKit e Google
A hierarquia de fallback de idiomas em 4 níveis
Quando um dispositivo móvel renderiza um passe localizado, a Passinstance aplica uma hierarquia de resolução em 4 níveis para garantir que o texto nunca aparece em branco ou quebrado:
-
1
Correspondência Exata de Locale: Se o dispositivo pedir
de-AT(Alemão - Áustria) e existir um dicionáriode-AT, este é carregado primeiro. -
2
Correspondência de Idioma Base: Se
de-ATestiver ausente, o motor recorre ade(Alemão). -
3
Idioma Principal do Modelo: Se
deestiver ausente, o motor recorre ao idioma base canónico do modelo (predefinição:en). -
4
Primeira Tradução Disponível: Se as strings base estiverem em falta, o compilador apresenta a primeira string traduzida disponível.
Elementos e ativos localizados
Pode localizar os seguintes componentes de qualquer modelo de passe:
| Elemento | Mecanismo Apple Wallet | Mecanismo Google Wallet | Exemplo |
|---|---|---|---|
| Rótulos de Campos | Chave mapeada em pass.strings | translatedValues no rótulo LocalizedString | "POINTS" -> "PUNKTE" / "POINTS DE FIDÉLITÉ" |
| Valores Estáticos de Campos | Chave mapeada em pass.strings | translatedValues no valor LocalizedString | "Gold Member" -> "Membre Or" |
| Mensagens Push de Alteração | Chave mapeada em pass.strings com marcador %@ | Payload de notificação push da Google Wallet | "Your balance is %@" -> "Ihr Guthaben beträgt %@" |
| Texto do Logótipo e Nome da Org. | Chave logoText em pass.strings | localizedString no cabeçalho da classe | "Artisan Cafe" -> "Café Artisan" |
| Imagens Localizadas | Armazenadas na pasta <lang>.lproj/ dentro do .pkpass | URI de imagem do fornecedor por classe localizada | Faixa promocional localizada com tipografia traduzida |
| Campos de Verso e Termos | Chaves de texto longo em pass.strings | Módulos localizados textModulesData | Termos e condições traduzidos por região |
Importante: Ao localizar notificações push de atualização (
changeMessage), tem de preservar o especificador de formato da Apple%@em todas as traduções (por exemplo,"Votre solde est désormais de %@"). Se%@for omitido de uma tradução localizada, o iOS suprimirá a notificação no ecrã bloqueado quando esse idioma estiver ativo.
Configurar localização no Editor Visual
-
1
Abra o seu modelo no Editor Visual.
-
2
Na barra lateral esquerda de navegação, aceda a Design e conteúdo -> Idiomas e traduções.
-
3
Clique em + Adicionar Idioma e selecione os códigos de idioma pretendidos (por exemplo, Alemão
de, Francêsfr, Espanholes). -
4
O editor apresenta uma grelha de tradução lado a lado com todas as chaves de campos, rótulos, valores e mensagens de alteração.
-
5
Introduza as strings traduzidas para cada campo.
-
6
Para carregar imagens específicas de um idioma (como uma faixa promocional em alemão com texto em alemão), clique em Imagens Localizadas no separador do idioma selecionado e carregue o PNG
@2x/@3xcorrespondente. -
7
Clique em Guardar Rascunho e pré-visualize as alterações no simulador alternando o seletor de idioma de pré-visualização.
API programática: Configurar strings multilingues
Pode gerir traduções através da API REST da Passinstance atualizando template.localization (PATCH /api/v1/templates/:id):
{
"localization": {
"defaultLanguage": "en",
"languages": ["de", "fr", "es"],
"translations": {
"de": {
"MEMBER_LABEL": "MITGLIED",
"POINTS_LABEL": "PUNKTESTAND",
"TIER_GOLD": "Goldstatus",
"CHANGE_POINTS_MSG": "Ihr neuer Punktestand ist %@",
"TERMS_TITLE": "ALLGEMEINE GESCHÄFTSBEDINGUNGEN",
"TERMS_BODY": "Punkte verfallen nach 12 Monaten Inaktivität."
},
"fr": {
"MEMBER_LABEL": "MEMBRE",
"POINTS_LABEL": "POINTS DE FIDÉLITÉ",
"TIER_GOLD": "Statut Or",
"CHANGE_POINTS_MSG": "Votre nouveau solde est de %@",
"TERMS_TITLE": "CONDITIONS GÉNÉRALES",
"TERMS_BODY": "Les points expirent après 12 mois d'inactivité."
}
}
}
}
Referência do formato de ficheiro pass.strings da Apple
Quando a Passinstance compila um pacote .pkpass da Apple Wallet, gera automaticamente ficheiros pass.strings codificados em UTF-16 (ou UTF-8 com BOM) dentro de pastas <locale>.lproj/:
/* de.lproj/pass.strings */
"MEMBER_LABEL" = "MITGLIED";
"POINTS_LABEL" = "PUNKTESTAND";
"CHANGE_POINTS_MSG" = "Ihr neuer Punktestand ist %@";
"TERMS_TITLE" = "ALLGEMEINE GESCHÄFTSBEDINGUNGEN";
Testar passes localizados em dispositivos móveis
Para confirmar que as suas regras de localização são apresentadas corretamente:
-
1
Testes em iOS:
- Aceda a Definições -> Geral -> Idioma e Região no seu iPhone. - Adicione o seu idioma de teste (por exemplo, Alemão) e defina-o como idioma principal do sistema. - Abra a Apple Wallet: todos os rótulos de campos e notificações push do passe serão atualizados para alemão.
-
2
Testes em Android:
- Aceda a Definições -> Sistema -> Idiomas e Introdução no seu dispositivo Android. - Mova Alemão ou Francês para o topo da sua lista de preferências de idioma. - Abra a Google Wallet para observar os módulos textModulesData e os valores de cabeçalho traduzidos.
-
3
Testes na Página de Transferência:
- As páginas de transferência do PassFlow (/p/:token) detetam automaticamente o cabeçalho Accept-Language do navegador e disponibilizam um seletor de idioma no rodapé.
Explore Design e configuração de modelos para ajustar estruturas visuais de cartões ou Versões e publicação de modelos para promover o seu modelo localizado para produção.
