O conceito central
Um aplicativo Bubble normalmente possui um linguagem canônica no qual foram criados seus rótulos de banco de dados, valores de exibição Option Set e condições de texto codificadas. GoLocal pode mostrar esses valores em outro idioma, mas a lógica Bubble ainda pode esperar o valor canônico.
Idioma de origem do projeto
Inglês
Categoria armazenada: Notícias
O visitante vê
Francês
Etiqueta visível: Actualités
Pesquisas Bubble
Notícias
Valor de origem normalizado
normalized_query é usado somente onde Bubble precisa explicitamente de texto no idioma de origem.Qual elemento GoLocal devo usar?
O plugin contém dois elementos Bubble não visuais diferentes. Eles resolvem problemas diferentes. A maioria das páginas precisa do principal GoLocal! elemento; apenas páginas com um problema específico de pesquisa de texto precisam GoLocal Query.
Tradutor obrigatório
GoLocal!
Este é o principal mecanismo de tradução. Ele carrega seu projeto, traduz o conteúdo da página, exibe o widget de idioma e publica o idioma atual e os eventos de tradução.
- Geralmente coloque uma instância em um cabeçalho reutilizável ou outro elemento compartilhado pela página.
- Use seus campos para a chave API, widget, IDs/seletores excluídos e comportamento de origem/destino.
- Use seus estados e eventos quando Bubble precisar saber o idioma selecionado ou o status da tradução.
Auxiliar lógico opcional
GoLocal Query
Isso não traduz a página e não exibe um widget. Ele converte uma frase de pesquisa inserida pelo visitante na frase canônica do idioma de origem do seu aplicativo para a lógica Bubble.
- Adicione-o somente quando uma entrada normal precisar pesquisar ou comparar texto armazenado no idioma de origem do projeto.
- Use um elemento de consulta por entrada de pesquisa independente.
- Nunca use normalized_query para salvar nomes, títulos, descrições ou mensagens criados pelo usuário.
Arquitetura Bubble preferida
Sempre que possível, crie condições em torno de coisas Bubble, opções Option Set, IDs exclusivos ou códigos estáveis – não texto de exibição traduzido. A tradução deve mudar o que uma pessoa vê, e não a identidade do registo.
Melhor: compare o objeto
Current cell's Article's Category
is Category NewsO visitante pode ver “Actualités”, mas Bubble compara a própria opção Category Thing ou Option Set.
Use Consulta apenas para correspondência de texto
Category name contains
GoLocal Query Categories's normalized_queryIsto é apropriado quando o banco de dados ou uma condição existente pesquisa genuinamente texto canônico em inglês.
Exemplo de conjunto de categorias
Pesquisa reversa automática
Tempo de execução gratuito 4.1.23 aplica automaticamente a pesquisa reversa apenas aos controles Bubble cuja finalidade é selecionar ou pesquisar um valor existente:
Tipos de visitantes: Atualidades
Partidas de controle: Notícias
O visitante continua a ver: Atualidades
Cada controle compatível possui estado reverso isolado, incluindo vários controles na mesma página. Não adicione um elemento GoLocal Query apenas para duplicar esse comportamento integrado.
Bubble SearchBox
Use-o quando o visitante pesquisar e selecionar uma coisa Bubble existente. GoLocal ajuda a frase traduzida a corresponder ao texto canônico usado pelo SearchBox.
Lista suspensa Bubble
Use-o para uma única seleção em uma lista estática ou dinâmica existente. A opção selecionada continua sendo o valor real de Bubble.
Bubble herdado MultiDropdown
Use-o para selecionar várias opções existentes em aplicativos Bubble mais antigos. Cada controle é normalizado de forma independente.
Select2 MultiDropdown
Use-o para controles de seleção múltipla pesquisáveis atuais. O texto de pesquisa digitado pode corresponder aos rótulos de opções do idioma de origem sem alterar as entradas comuns.
Usando GoLocal Query
Use o não visual GoLocal Query elemento quando uma entrada Bubble comum aciona intencionalmente uma pesquisa de texto, condicional de idioma de origem ou filtro de backend/API.
Adicione um elemento de consulta para esta entrada
Coloque-o uma vez na página ou no elemento reutilizável que possui o Input. Não o coloque em todas as células do grupo de repetição.
Element name: GoLocal Query CategoriesVincule seu campo de consulta
Query = Input Category Search's value
Enabled = yes
Debounce (ms) = 180Bubble atualiza automaticamente o elemento quando o valor de entrada dinâmico muda. Nenhum fluxo de trabalho com alteração de entrada é necessário.
Use normalized_query somente na lógica do idioma de origem
GoLocal Query Categories's normalized_queryUse esse valor em uma restrição de grupo de repetição, filtro avançado, condicional de texto ou parâmetro API que espera inglês.
Mantenha os salvamentos e a validação conectados à entrada
Save Category Name = Input Category Search's valueNunca substitua um valor salvo normal, verificação de e-mail, cálculo de número ou verificação de campo obrigatório por normalized_query.
O que acontece enquanto o visitante digita?
- 1A entrada muda: Bubble passa o valor de entrada atual exato para o campo Consulta.
- 2Debounce espera brevemente: O padrão de 180 ms impede uma solicitação para cada pressionamento de tecla.
- 3A frase mais recente está normalizada: Por exemplo, “Actualités” é resolvido para “Notícias”. Solicitações inacabadas mais antigas não podem substituir o resultado mais recente.
- 4Bubble recebe os estados: normalized_query torna-se “Notícias”, is_normalizing torna-se não e o evento normalizado é acionado.
- 5Somente a lógica pretendida o consome: O filtro de grupo de repetição, condicional ou API usa normalized_query; os salva ainda usam a entrada original.
Exemplos práticos de Bubble
Grupo repetitivo
Pesquise categorias de artigos em inglês a partir de uma entrada em francês
Os tipos de visitantes Atualidades. O banco de dados armazena Notícias. Defina a restrição de nome de categoria do grupo repetidor como:
GoLocal Query Categories's normalized_queryPrefira uma seleção de Categoria Thing/Option Set quando disponível; use a normalização de texto somente quando o filtro for realmente baseado em texto.
Bubble condicional
Compare com um valor do idioma de origem codificado
When GoLocal Query Status's is_normalizing is no
and GoLocal Query Status's normalized_query is "Archived"Se a condição controlar um fluxo de trabalho crítico, aguarde até que a normalização termine. Para filtragem somente de exibição, o substituto bruto pode ser suficiente.
Back-end ou API
Envie uma consulta em linguagem canônica para um endpoint
API parameter q = GoLocal Query Products's normalized_query
Run only when is_normalizing is noIDs, UUIDs, e-mails, tokens, datas e valores numéricos devem ignorar GoLocal Query e ser enviados inalterados.
Passo a passo completo para iniciantes
Filtre artigos por um nome de categoria traduzido
Suponha que o aplicativo foi desenvolvido em inglês. O campo do banco de dados Nome da categoria contém Notícias, mas um visitante francês digita Atualidades em uma entrada normal.
Input Category SearchGoLocal Query CategoriesGoLocal Query Categories → Query
= Input Category Search's valueSearch for Articles
Category name = GoLocal Query Categories's normalized_queryCreate a new Article's title
= Input Article Title's valueResultado: o visitante pesquisa em francês, Bubble encontra o valor do banco de dados em inglês e nenhum texto inserido pelo usuário é reescrito ou salvo em outro formato.
Páginas com múltiplas entradas
Crie uma instância GoLocal Query para cada contexto de pesquisa independente. Cada instância tem seu próprio valor, temporizador de rejeição, proteção de sequência, estados e eventos, portanto, uma entrada não pode substituir outra.
Pesquisa de artigos de entradaArtigos GoLocal QueryGrupo de repetição de artigosInsira a pesquisa do clienteClientes GoLocal QueryFiltro API do clienteFiltro de tags de entradaGoLocal Query TagsCondição da etiquetanormalized evento dispara.O que deve permanecer intocado
Use GoLocal Query para
- Texto de formato livre usado para pesquisar campos de banco de dados em linguagem canônica
- Condições de texto que esperam uma constante em inglês
- Parâmetros de consulta API cujo backend espera inglês
- Controles de pesquisa de terceiros que expõem a consulta digitada a Bubble
Não use para
- Nomes, títulos, comentários, descrições ou tags criadas pelo usuário sendo salvos
- Quill, rich-text, contenteditable ou conteúdo de entrada multilinha
- E-mails, senhas, telefones, IDs, datas, números, arquivos ou validação
- Bubble Coisas ou objetos Option Set que podem ser comparados diretamente
Conteúdo salvo do usuário exibido posteriormente
Uma entrada protegida ainda pode ser renderizada posteriormente dentro de um elemento de texto Bubble normal. Marque o contêiner de exibição com uma classe reutilizável, como .gl-user-content e adicione-o ao elemento GoLocal principal do_not_translate_selectors. Para grupos repetidos, use uma classe/seletor em vez de duplicar o mesmo ID HTML nas linhas.
Campos, estados e eventos
Campos
QuerytextVincule a um valor de entrada Bubble visível.
Enabledyes/noPadrão sim. Quando desativado, o texto cortado passa inalterado.
Debounce (ms)numberO padrão é 180. O intervalo recomendado para pesquisa é de 150 a 250 ms.
Estados
original_querytextValor exato recebido de Bubble antes da normalização.
normalized_querytextValor canônico do idioma de origem para lógica de pesquisa ou comparação.
is_normalizingyes/noSim, enquanto a consulta não vazia mais recente está sendo resolvida.
normalization_foundyes/noSim, quando um mapeamento do idioma de origem foi encontrado.
last_errortextMensagem de falha técnica; vazio durante a operação normal.
normalizado
Dispara após a conclusão da última consulta. Use-o quando um fluxo de trabalho precisar aguardar ou copiar o resultado em um estado personalizado.
normalization_failed
Incêndios por falha técnica. A consulta bruta permanece como um substituto utilizável e os detalhes aparecem em last_error.
Solução de problemas de configurações comuns do Bubble
normalized_query sempre é igual à entrada bruta
Confirme se o elemento principal GoLocal! está presente e pronto, o idioma de origem do projeto está configurado corretamente e o campo Consulta está vinculado à entrada pretendida. Uma frase desconhecida pode usar intencionalmente o texto bruto como uma alternativa segura.
O grupo de repetição mostra brevemente o resultado anterior
Para filtragem estrita, mostre um estado de carregamento ou execute a pesquisa final somente quando o estado is_normalizing do elemento de consulta correspondente for não. A proteção de sequência evita que uma solicitação mais antiga substitua um resultado mais recente.
Um título ou descrição salvo foi alterado
O fluxo de trabalho de salvamento faz referência a normalized_query ou ao texto de exibição traduzido. Altere-o de volta para o valor original de entrada, entrada multilinha ou editor de rich text. GoLocal Query é apenas para lógica correspondente.
Duas entradas interferem uma na outra
Dê a cada entrada de pesquisa independente seu próprio elemento GoLocal Query. Não alterne dinamicamente um auxiliar entre entradas não relacionadas.
Um seletor de terceiros não faz correspondência reversa
O suporte automático é limitado a Bubble SearchBox, menu suspenso Bubble, MultiDropdown herdado e Select2 MultiDropdown. Se o controle de terceiros expor o texto digitado para Bubble, conecte esse texto a um elemento GoLocal Query dedicado.
O conteúdo salvo do usuário é traduzido quando exibido posteriormente
Adicione uma classe reutilizável como .gl-user-content ao seu contêiner de exibição e inclua esse seletor em do_not_translate_selectors no elemento GoLocal! principal.
A entrada está dentro de um grupo de repetição
Não coloque um elemento de consulta em cada célula e não duplique os IDs HTML. Prefira filtrar o grupo repetidor antes de renderizá-lo; caso contrário, mantenha o auxiliar de consulta fora do grupo de repetição e passe um único valor selecionado/pesquisado para ele.
Lista de verificação de aceitação
- 1Procure o mesmo registro em inglês e francês.
- 2Digite rapidamente e confirme que um resultado mais antigo nunca substitui um mais recente.
- 3Limpe a entrada e confirme as redefinições de grupo repetidas.
- 4Mude o idioma enquanto a entrada não estiver vazia.
- 5Teste duas entradas de pesquisa independentes na mesma página.
- 6Salve um título em francês com acentos e confirme se o texto exato está armazenado.
- 7Digite e cole em Quill; nenhum caminho deve ser reescrito.
- 8Teste uma consulta desconhecida e confirme se o substituto bruto mantém a página utilizável.
- 9Confirme se cada fluxo de trabalho salvo usa o valor de entrada original.
- 10Confirme se os fluxos de trabalho críticos no idioma de origem aguardam is_normalizing = não.
Regra de decisão rápida
Exibir e salvar use a entrada. A correspondência canônica de texto usa GoLocal Query.
Se Bubble puder comparar uma coisa, opção Option Set, ID ou código estável, use esse objeto diretamente. Adicione GoLocal Query somente quando um valor de texto de formato livre traduzido precisar corresponder ao texto canônico do idioma de origem.