Skip to content
Guia da Central de Ajuda · Modelos de passes
5 min de leituraVerificado 2026-11-16

Idiomas do passe e localização

Distribua passes multilíngues da Apple e Google Wallet usando dicionários .lproj/pass.strings, imagens localizadas e árvores de fallback.

Neste guia

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 .lproj da Apple Wallet: Dicionários padrão de strings Apple PassKit (<language>.lproj/pass.strings) empacotados diretamente no arquivo .pkpass juntamente com imagens localizadas.
  • Recursos LocalizedString da 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

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
LOCALIZAÇÃO DE PASSES E COMPILAÇÃO DE STRINGS
ETAPA 01 REPOSITÓRIO DE LOCALIZAÇÃO DE MODELOS (templateLocalization.ts)
Idioma Base (ex., en): Rótulos, valores e mensagens de alteração canónicos
Dicionários de Tradução: de, es, fr, it, nl, pt, ja, etc.
Substituições Visuais: localizedImages[locale] (ex., faixa em alemão)
ETAPA 02 COMPILADOR DE LOCALIZAÇÃO (template-localization.util.ts)
1
Escapa literais UTF-16 / UTF-8 da Apple ("Key" = "Translated Value";)
2
Preserva especificadores de formato (%@) em changeMessage em todos idiomas
3
Constrói hierarquia de fallback: ExatoIdioma BaseModelo Principal
ETAPA 03A APPLE WALLET (Pacote .pkpass)
de.lproj/pass.strings de.lproj/logo.png, strip.png fr.lproj/pass.strings fr.lproj/logo.png
O iOS apresenta conforme o idioma
ETAPA 03B GOOGLE WALLET (Class/Object)
"label": { "defaultValue": { "language": "en", "value": "POINTS" }, "translatedValues": [ { "language": "de", "value": "PUNKTE" } ]
}

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. 1
    Correspondência Exata de Locale: Se o dispositivo pedir de-AT (Alemão - Áustria) e existir um dicionário de-AT, este é carregado primeiro.
  2. 2
    Correspondência de Idioma Base: Se de-AT estiver ausente, o motor recorre a de (Alemão).
  3. 3
    Idioma Principal do Modelo: Se de estiver ausente, o motor recorre ao idioma base canónico do modelo (predefinição: en).
  4. 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:

ElementoMecanismo Apple WalletMecanismo Google WalletExemplo
Rótulos de CamposChave mapeada em pass.stringstranslatedValues no rótulo LocalizedString"POINTS" -> "PUNKTE" / "POINTS DE FIDÉLITÉ"
Valores Estáticos de CamposChave mapeada em pass.stringstranslatedValues no valor LocalizedString"Gold Member" -> "Membre Or"
Mensagens Push de AlteraçãoChave 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.stringslocalizedString no cabeçalho da classe"Artisan Cafe" -> "Café Artisan"
Imagens LocalizadasArmazenadas na pasta <lang>.lproj/ dentro do .pkpassURI de imagem do fornecedor por classe localizadaFaixa promocional localizada com tipografia traduzida
Campos de Verso e TermosChaves de texto longo em pass.stringsMódulos localizados textModulesDataTermos 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. 1
    Abra o seu modelo no Editor Visual.
  2. 2
    Na barra lateral esquerda de navegação, aceda a Design e conteúdo -> Idiomas e traduções.
  3. 3
    Clique em + Adicionar Idioma e selecione os códigos de idioma pretendidos (por exemplo, Alemão de, Francês fr, Espanhol es).
  4. 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. 5
    Introduza as strings traduzidas para cada campo.
  6. 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 / @3x correspondente.
  7. 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):

JSON
{
  "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/:

TEXT
/* 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. 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.

  1. 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.

  1. 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.

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.