核心理念
Bubble 应用程序通常有一个 规范语言 其中创建了数据库标签、Option Set 显示值和硬编码文本条件。 GoLocal 可能会以另一种语言显示这些值，但 Bubble 逻辑仍然可以期望规范值。
Project 源
英语
存储类别：新闻
访客看到
法语
可见标签：现状
Bubble 搜索
新闻动态
标准化源值
normalized_query 仅在 Bubble 明确需要源语言文本的情况下使用。我应该使用哪个 GoLocal 元素？
该插件包含两个不同的非视觉 Bubble 元素，它们解决不同的问题。大多数页面都需要主 GoLocal! 元素；只有具有特定文本搜索问题的页面才需要 GoLocal Query。
所需译员
GoLocal!
这是主要的翻译引擎。它加载您的项目，翻译页面内容，显示语言小部件，并发布当前语言和翻译事件。
- 通常将一个实例放置在可重用标头或页面共享的另一元素中。
- 将其字段用于 API 键、小部件、排除的 ID/选择器和源/目标行为。
- 当 Bubble 必须知道所选语言或翻译状态时，使用其状态和事件。
可选逻辑助手
GoLocal Query
这不会翻译页面，也不会显示小部件。它将访问者输入的搜索短语转换为应用程序的 Bubble 逻辑的规范源语言短语。
- 仅当普通输入必须搜索或比较以项目源语言存储的文本时才添加它。
- 每个独立搜索输入使用一个查询元素。
- 切勿使用 normalized_query 保存用户创建的名称、标题、描述或消息。
首选 Bubble 架构
只要有可能，围绕 Bubble 事物、Option Set 选项、唯一 ID 或稳定代码（而不是翻译的显示文本）构建条件。翻译应该改变人们所看到的，而不是记录的身份。
最佳：比较物体
Current cell's Article's Category
is Category News访问者可能会看到“Actualités”，但 Bubble 会比较类别事物或 Option Set 选项本身。
仅使用查询进行文本匹配
Category name contains
GoLocal Query Categories's normalized_query当数据库或现有条件真正搜索规范英语文本时，这是合适的。
类别集示例
自动反向查找
免费运行时间 4.1.23 仅自动将反向查找应用于其目的是选择或搜索现有值的 Bubble 控件：
访客类型： 现状
控制匹配： 新闻动态
访客继续看到： 现状
每个受支持的控件都有独立的反向状态，包括同一页面上的多个控件。不要仅仅为了复制此内置行为而添加 GoLocal Query 元素。
Bubble SearchBox
当访问者搜索并选择现有的 Bubble 事物时使用它。 GoLocal 帮助翻译的短语与 SearchBox 使用的规范文本相匹配。
Bubble 下拉菜单
将其用于从现有静态或动态列表中进行单个选择。所选选项保留实际的 Bubble 值。
旧版 Bubble MultiDropdown
使用它来选择旧版 Bubble 应用程序中的多个现有选项。每个控件都独立标准化。
Select2 MultiDropdown
将其用于当前可搜索的多选控件。输入的搜索文本可以匹配源语言选项标签，而无需更改普通输入。
使用 GoLocal Query
当普通 Bubble 输入有意驱动文本搜索、源语言条件或后端/API 过滤器时，使用非视觉 GoLocal Query 元素。
为此输入添加一个查询元素
将其放置在页面上或拥有输入的可重用元素中一次。不要将其放置在每个重复组单元格中。
Element name: GoLocal Query Categories绑定其查询字段
Query = Input Category Search's value
Enabled = yes
Debounce (ms) = 180当动态输入值发生变化时，Bubble 会自动更新元素。不需要输入更改的工作流程。
仅在源语言逻辑中使用 normalized_query
GoLocal Query Categories's normalized_query在重复组约束、高级过滤器、文本条件或需要英语的 API 参数中使用此值。
保持保存和验证连接到输入
Save Category Name = Input Category Search's value切勿用 normalized_query 替换正常的保存值、电子邮件检查、数字计算或必填字段检查。
访客打字时会发生什么？
- 1输入变化: Bubble 将准确的当前输入值传递到查询字段。
- 2去抖动等待短暂: 默认的 180 毫秒可防止每次击键发出请求。
- 3最新短语已标准化: 例如，“Actualités”被解析为“News”。较旧的未完成请求无法覆盖最新结果。
- 4Bubble 接收状态: normalized_query 变为“新闻”，is_normalizing 变为否，并且触发标准化事件。
- 5只有预期的逻辑才会消耗它: 重复组、条件或 API 过滤器使用 normalized_query；保存时仍然使用原来的Input。
实用Bubble示例
重复组
从法语输入中搜索英语文章类别
访客类型 现状。数据库存储 新闻动态。将重复组的类别名称约束设置为：
GoLocal Query Categories's normalized_query首选类别事物/Option Set 选择（如果有）；仅当过滤器确实基于文本时才使用文本标准化。
Bubble 有条件
与硬编码的源语言值进行比较
When GoLocal Query Status's is_normalizing is no
and GoLocal Query Status's normalized_query is "Archived"如果条件控制关键工作流程，请等待标准化完成。对于仅显示过滤，原始回退可能就足够了。
后端或 API
向端点发送规范语言查询
API parameter q = GoLocal Query Products's normalized_query
Run only when is_normalizing is noID、UUID、电子邮件、令牌、日期和数值应绕过 GoLocal Query 并原封不动地发送。
完整的初学者演练
按翻译的类别名称过滤文章
假设该应用程序是用英语构建的。数据库字段 类别名称 包含 新闻动态，但是一位法国访客输入 现状 进入正常输入。
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 value结果：访问者用法语搜索，Bubble 找到英语数据库值，并且用户输入的文本不会被重写或以其他形式保存。
具有多个输入的页面
为每个独立搜索上下文创建一个 GoLocal Query 实例。每个实例都有自己的值、反跳计时器、序列保护、状态和事件，因此一个输入不能覆盖另一个输入。
输入文章搜索GoLocal Query 文章文章重复组输入客户搜索GoLocal Query 客户客户 API 过滤器输入标签过滤器GoLocal Query标签标签条件normalized 事件发生。什么必须保持不变
使用 GoLocal Query 进行
- 用于搜索规范语言数据库字段的自由格式文本
- 需要英文常量的文本条件
- API 后端需要英文的查询参数
- 将其键入的查询公开给 Bubble 的第三方搜索控件
请勿将其用于
- 保存的名称、标题、评论、描述或用户创建的标签
- Quill、富文本、contenteditable 或多行输入内容
- 电子邮件、密码、电话、ID、日期、数字、文件或验证
- Bubble 可直接比较的事物或 Option Set 对象
保存的用户内容稍后显示
受保护的输入稍后仍可以在普通的 Bubble 文本元素内呈现。使用可重用的类标记显示容器，例如 .gl-user-content 并将其添加到主 GoLocal 元素中 do_not_translate_selectors。对于重复组，请使用类/选择器，而不是跨行复制相同的 HTML ID。
字段、状态和事件
领域
Querytext绑定到一个可见的 Bubble 输入值。
Enabledyes/no默认是。禁用后，修剪后的文本将保持不变。
Debounce (ms)number默认 180。建议搜索范围为 150–250 毫秒。
州
original_querytext标准化前从 Bubble 收到的精确值。
normalized_querytext用于搜索或比较逻辑的规范源语言值。
is_normalizingyes/no是的，正在解决最新的非空查询。
normalization_foundyes/no是，当找到源语言映射时。
last_errortext技术故障消息；正常运行期间为空。
归一化
最新查询完成后触发。当工作流必须等待或将结果复制到自定义状态时使用它。
错误
技术故障时触发。原始查询仍可作为后备，详细信息显示在 last_error 中。
对常见 Bubble 设置进行故障排除
normalized_query 始终等于原始输入
确认主 GoLocal! 元素存在并准备就绪，项目源语言配置正确，并且查询字段已绑定到预期的输入。未知短语可能会故意使用原始文本作为安全后备。
重复组简要显示先前的结果
对于严格过滤，仅当匹配的查询元素的 is_normalizing 状态为 no 时才显示加载状态或运行最终搜索。序列保护防止较旧的请求替换较新的结果。
已保存的标题或描述已更改
保存工作流程引用 normalized_query 或翻译的显示文本。将其更改回原始输入、多行输入或富文本编辑器值。 GoLocal Query 仅用于匹配逻辑。
两个输入互相干扰
为每个独立的搜索输入提供其自己的 GoLocal Query 元素。不要在不相关的输入之间动态切换一个助手。
第三方选择器不进行反向匹配
自动支持仅限于 Bubble SearchBox、Bubble Dropdown、旧版 MultiDropdown 和 Select2 MultiDropdown。如果第三方控件向 Bubble 公开键入的文本，请将该文本连接到专用的 GoLocal Query 元素。
保存的用户内容稍后显示时会被翻译
将可重用类（例如 .gl-user-content）添加到其显示容器中，并将该选择器包含在主 GoLocal! 元素上的 do_not_translate_selectors 中。
输入位于重复组内
不要在每个单元格中放置一个查询元素，并且不要重复 HTML ID。在渲染之前优先过滤重复组；否则，将查询助手保留在重复组之外，并将单个选定/搜索值传递到其中。
验收清单
- 1用英语和法语搜索相同的记录。
- 2快速输入并确认旧结果不会取代新结果。
- 3清除输入并确认重复组重置。
- 4当输入不为空时切换语言。
- 5在同一页面上测试两个独立的搜索输入。
- 6保存带有重音符号的法语标题并确认存储了准确的文本。
- 7输入并粘贴到 Quill 中；两条路径都不应该被重写。
- 8测试未知查询并确认原始后备保持页面可用。
- 9确认每个保存工作流程都使用原始输入值。
- 10确认关键源语言工作流程等待 is_normalizing = 否。
快速决策规则
显示和保存使用输入。规范文本匹配使用 GoLocal Query。
如果 Bubble 可以比较事物、Option Set 选项、ID 或稳定代码，请直接使用该对象。仅当翻译的自由格式文本值必须与规范源语言文本匹配时，才添加 GoLocal Query。