完整的设置指南
安装、配置和使用 GoLocal! 使您的 Bubble.io 应用程序多语言所需的一切。
安全的Bubble数据、稳定的UI翻译、明确的多语言逻辑
从 Bubble 更新插件 插件 在测试以下功能之前。 Project 配置、翻译和计费仍然附加到 GoLocal 项目。应用程序开发人员无需在 Bubble 的 HTML 标头中粘贴或维护脚本；发布的插件版本包含支持的运行时。
可编辑数据保持不变
用户键入时，普通输入、多行输入、Quill 编辑器和其他 contenteditable 区域不会反向翻译。
可重复使用的内容排除
保护用户输入的数据库值和带有 do_not_translate_selectors 的重复组单元格，而不是重复的 HTML ID。
安全自动反向查找
Bubble SearchBox、下拉菜单、旧版 MultiDropdown 和 Select2 MultiDropdown 可以将翻译的选择与源语言值进行匹配。
GoLocal Query 元素
仅当输入驱动源语言文本搜索、条件或 API 过滤器时，每个普通输入才使用一个独立的 GoLocal Query 元素。
1 安装插件
GoLocal! 可用作 免费插件 在 Bubble.io 市场上。您无需支付任何费用即可安装它 — 插件本身的成本为 0 美元。仅当您使用 API 密钥将其连接到 GoLocal! 项目时才需要计费。
打开 Bubble 编辑器 → 插件选项卡。
单击“+ 添加插件”并搜索“GoLocal”或“自动翻译器”。
安装 GoLocal! — 自动翻译器。如果已安装，请将其更新到最新发布的版本。
将 GoLocal! 元素拖动到任何页面（通常是可重用标题）。该元素是不可见的。
2 创建您的帐户 & Project
要激活该插件，您需要 API 键。当您创建项目时，API 密钥会在 GoLocal! 仪表板中生成。
一个 5 天免费试用 自动启动。无需信用卡。你的 API 键 立即生成。
复制 API 密钥 - 在 Bubble 中配置插件时需要它。
myapp.bubbleapps.io，准确输入。3 配置插件
单击 GoLocal! 元素。至少设置 一个字段:
最低要求设置：
api_key→ 粘贴 GoLocal! 项目中的 API 密钥只需按下 API 键，GoLocal! 即可加载项目配置，使用访问者的浏览器或保存的小部件选择，翻译可见的 UI 文本，并显示语言切换器。
4 插件字段 - 参考
api_key必填GoLocal! 仪表板中您项目的 API 密钥。
域绑定——可以安全地包含在客户端代码中。
source_language可选应用原始语言的两个字母代码。示例： en, uk, de.
当源语言已在 GoLocal 项目中配置时，通常将其留空。仅当您有意需要覆盖项目/工作人员值时才设置它。
target_language可选通常将此字段留空。 小部件和访问者的持久选择控制跨页面加载的活动语言。
硬编码值，例如 fr 每当元素初始化时都会强制使用该语言，并且可以覆盖访问者的选择。仅当您的 Bubble 应用程序有意拥有语言状态并在每个页面上提供一个稳定的语言代码时，才绑定动态值。
enabled可选控制翻译是否处于活动状态的复选框。默认值： 检查过.
show_widget可选显示内置语言切换器小部件。默认值： 检查过。仅当您的 Bubble 应用程序提供自己的语言控制和调用时才将其关闭 switch_language.
widget_position可选小部件位置： bottom-right （默认）， bottom-left, top-right, top-left.
dataset_1可选预翻译您的 Bubble 数据库以便即时加载。
结构化格式（推荐）：
// Bubble 设置：
搜索（类别）：格式为文本
内容： {该类别的标题；该类别的名称；该类别的主体}
分隔符： ,
// 添加另一种类型：
:append 搜索 (Cures) :format as text
内容： {本疗法的标题；此疗法的名称；此药的处方}
分隔符： ,
里面的字段 { } 隔开 ; — 块分隔 ,。参见 数据集 了解详情。
do_not_translate_ids可选以逗号分隔的元素 ID 从不翻译。指定组/容器 ID 会排除所有子项。
示例： user-bio, code-block, brand-section
HTML ID 必须是唯一的。不要在重复组小区中重复使用相同的 ID；将 do_not_translate_selectors 与类一起使用。
do_not_translate_selectors可选用于可重用或重复内容的 CSS 选择器，这些内容必须与存储时完全相同。匹配的元素及其所有子元素都被排除。
示例： .gl-user-content, [data-user-content], [id^="gl-user-content-"]
建议用于用户输入的数据库值和重复组。类或 ID 前缀选择器可以安全地匹配许多行，而无需创建重复的 HTML ID。
private_translate_ids可选元素 被翻译 但翻译 没有全局缓存。用于每个用户的数据（姓名、地址）。
示例： user-name, order-address
如果内容必须与用户输入的内容完全相同，则不要使用此字段。使用 do_not_translate_selectors 来排除它。
5 数据集 — 翻译您的 Bubble 数据库
大多数 Bubble 应用程序显示数据库中的数据。如果没有数据集，动态内容会在第一次查看时进行翻译，从而导致明显的延迟。数据集预翻译了所有内容 即时加载.
格式 1：结构化 — 适用于多字段项目（推荐）
将每个项目包裹在 {}，用分隔字段 ; （分号），使用 , 作为项目之间的分隔符。
// Bubble：搜索（类别）：格式为文本
内容： {该类别的标题；该类别的名称；该类别的主体}
分隔符： ,
// 附加：搜索 (Cures) :format as text
内容： {本疗法的标题；此疗法的名称；此药的处方}
分隔符： ,
// 结果： {健康；保健；指南...},{美容；护肤；日常护理...},{阿司匹林；缓解；服用 2 次...}
{} 分割为 ; — 块分割为 , — 文本中的逗号是安全的。格式 2：简单 — 用于单值列表
对于不带逗号的短值（类别名称、标签）：
内容： 该类别的名称 分隔符： ,
// 输出：电子产品、服装、书籍、玩具
重要： 如果文本可能包含逗号，请始终使用结构化格式 {field;field} 包装。
normalized_query。 请参阅完整的 Bubble 指南。6 Bubble 状态、事件和操作
主要的 GoLocal! 元素拥有页面翻译并将活动语言公开给 Bubble。使用条件及其事件中的状态在翻译生命周期的正确点启动工作流程。
1. 运行时准备就绪
translator_ready = yes 表示 GoLocal 已初始化。这并不意味着每个动态 Bubble 元素都已完成翻译。
2. 语言改变
language_changed 当活动语言更改时触发。阅读 current_language 在这里。
3.通过完成
translation_complete 翻译批次完成后触发。动态内容可能会创建稍后的批次。
current_languagetext活动的两字母语言代码。将其用于 PDF 链接、Bubble 条件和应用程序拥有的语言 UI。
detected_languagetext运行时报告的检测到的源/浏览器语言。
translator_readyyes/no是，在翻译运行时初始化之后。
is_translatingyes/noGoLocal 正在处理翻译时为是。
translation_completeyes/no最近一次传递的完成标志。
total_textsnumber当前运行时会话中观察到的文本项数。
cached_local / cached_bundle / cached_servernumber诊断缓存计数器。对于支持和性能检查很有用。
translated / errors / tokens_usednumber运行时翻译和错误计数器。
last_error / preload_statustext用于诊断的最新运行时错误和预加载状态。
元素动作
switch_language— 切换到所需的操作字段target_lang，例如fr.Start_translation— 开始或恢复观察和翻译。Stop_translation— 停止观察和翻译，直到重新启动。rescan_dom— 显式扫描 Bubble 弹出窗口、可重用元素或重复组更新后呈现的内容。
示例：显示法语 PDF 链接
在链接或组上创建 Bubble 条件： When GoLocal! A's current_language is "fr"。如果访问者切换语言时必须运行工作流，请使用 When GoLocal! A language_changed。您无需等待 translation_complete 只是为了阅读所选的语言。
7 用户数据、表格和重复组
GoLocal 翻译界面文本，但用户输入或创建的数据必须保持稳定。当前运行时保护普通输入、多行输入、Quill 编辑器和其他 contenteditable 当一个人打字时的区域。
默认安全
- • 输入和多行输入值完全按照键入的方式保存。
- • Quill
.ql-editor打字时会跳过其他可编辑区域。 - • 电子邮件、密码、数字、日期、ID 和文件应始终使用其原始 Bubble 值。
显示需要排除
当保存的用户内容稍后通过普通的 Bubble Text 元素显示时，GoLocal 无法知道它是 UI 副本还是用户数据。将该显示元素或其最小容器标记为非翻译区域。
推荐的重复组设置
- 1. 仅选择显示用户内容的文本元素。 如果整个重复组的按钮、标题和静态标签仍应翻译，请勿排除整个重复组。
- 2. 为每一行指定一个唯一的动态 ID。gl-user-content-当前单元格事物的唯一ID
- 3. 向 GoLocal 元素添加一个选择器。do_not_translate_selectors = [id^="gl-user-content-"]
如果您的 Bubble 设置或可重用元素可以应用自定义类， .gl-user-content 就更简单了。将该类添加一次到 do_not_translate_selectors.
支持的无翻译标记
运行时尊重 data-tr-skip, data-no-translate, translate="no"，并嵌套 .notranslate 元素。配置的 ID 和 CSS 选择器字段仍然是最简单的 Bubble 原生方法。
跳过与私人翻译
do_not_translate_* 保留原始值。 private_translate_ids 仍然转换该值，但阻止共享全局缓存。仅当内容真正需要翻译时才使用私人翻译。
home 或 check_box。如果图标是文本支持的，请排除最小的图标/控件容器，以便永远不会翻译字形关键字。8 翻译编辑和手动更正
使用翻译编辑器进行固定产品文案：导航标签、标题、按钮、帮助文本以及其他应经过审阅翻译的短语。手动输入被锁定，并且不会被以后的自动翻译取代。
良好的手动校正
来源 升级计划 → 复习法语产品短语 计划的改善者。这是稳定的界面副本，属于编辑器。
不要一次一行地更正用户数据
客户创建的名称，例如 住所劳动 应在 Bubble 显示元素处排除。添加数千个身份翻译并不能安全地替代无翻译区域。
- 1. 在 GoLocal 仪表板中打开项目并选择 翻译.
- 2. 搜索确切的源短语和语言对。
- 3. 编辑目标值，或使用 添加翻译 以获得新的确切源短语。
- 4. 保存。该条目已标记 手册，bundle版本发生变化，运行时刷新项目字典。
- 5. 重新测试该短语呈现的确切 Bubble 路线。使用
rescan_dom仅当该短语出现在不寻常的第三方渲染之后时。
en → fr, 不 auto → fr。运行时请求项目的解析源对。9 翻译工作原理
GoLocal 监视渲染的 Bubble DOM，首先应用项目包和本地缓存中的翻译，并仅请求丢失或更改的短语。它继续观察 Bubble 稍后渲染的弹出窗口、可重用元素和重复组。
初始页面加载
运行时解析源语言和目标语言，加载当前项目包，扫描可见的 UI 文本，并通过内置的防闪烁流程显示页面。
缓存翻译
已知短语从捆绑包或浏览器缓存中应用，无需重新生成。更改的捆绑包版本会使过时的缓存值失效。
动态Bubble内容
DOM 观察者拾取新渲染的弹出窗口、可重用元素、条件可见组和重复组单元格。 rescan_dom 是一个明确的后备。
10 故障排除和发布测试
页面重置为一种语言
将每个页面上的 target_language 留空并保留可重用的 GoLocal 元素，除非您的 Bubble 应用故意拥有该语言。初始化时重新应用硬编码值。
小部件丢失
确认 show_widget 已选中，最新的插件版本已安装，并且只有一个预期的 GoLocal 元素控制该页面。然后在 Bubble 逐步调试器模式之外进行测试。
弹出或新的重复组行保持未翻译
等待元素变得可见。观察者通常会自动发现它；如果第三方元素呈现异常，请在显示弹出窗口或组后运行 rescan_dom。
输入或富文本在键入时发生变化
更新插件，确认当前运行时，并验证保存工作流程是否读取原始输入/编辑器值，而不是翻译的显示文本或 normalized_query。
用户创建的法语文本再次被翻译
通过do_not_translate_selectors排除显示文本/容器。 保护是最小的动态值，并非所有静态 UI 都围绕它。
手动校正返回自动
当前的手动条目已被锁定。确认您编辑的源文本和运行时使用的语言对完全相同，然后将项目、路线、短语和测试时间发送给支持人员。
月/日名称保留为英文
本机浏览器或 Bubble 日期选择器 chrome 遵循浏览器/控件区域设置。 GoLocal 会翻译周围的标签，但不会重写内部日期选择器 UI。
Chrome 提供自己的页面翻译
该插件已经将文档标记为 notranslate 以进行浏览器翻译，同时允许 GoLocal 本身运行。更新插件；不要添加第二个翻译扩展或脚本。
翻译后文本换行方式不同
GoLocal 保留 Bubble 排版。翻译的短语可能会更长，因此请在每个断点处验证 Bubble 最小宽度、最大宽度、适合高度、溢出和响应规则。
Bubble 验收清单
- ✓切换源 → 目标 → 源，无需刷新。
- ✓在所有 Bubble 页面和可重用标题之间导航。
- ✓页面加载后打开弹出窗口并加载重复组行。
- ✓输入、粘贴、编辑、保存和重新打开普通文本和富文本字段。
- ✓测试每个重复组内排除的一个用户数据值。
- ✓测试 SearchBox、下拉菜单、传统/Select2 MultiDropdown 搜索。
- ✓测试每个 current_language 条件和 PDF/资源链接。
- ✓重新测试 Chrome、Safari、移动宽度和私人会话。
[GoLocal v4].11 定价& 计费
三个计划，全部都有 无限翻译字数和无限目标语言.
| 特点 | Starter | Pro | Business |
|---|---|---|---|
| 每月价格 | $15/mo | $35/mo | $89/mo |
| 年价 | $149/yr | $349/yr | $890/yr |
| 目标语言 | 无限 | 无限 | 无限 |
| MAU限制 | 30K | 150K | 1M |
| 项目 | 1 | 1 | 2 |
MAU
看过翻译的独特访客。机器人被过滤掉。免 10% 超额费用，然后额外支付 3/10K 美元。
语言
所有付费计划都包含无限的目标语言，无需额外按语言付费。
5 天免费试用
每个新项目都从免费试用开始。无需信用卡。
12 合作伙伴 Program
通过推荐GoLocal!赚钱
分享您的推荐链接 — 赚取收入 经常性佣金 对于您带来的每一位付费客户。
注册成为合作伙伴
仪表板→合作伙伴选项卡→“加入合作伙伴Program”。获取您独特的推荐链接。
分享您的链接
博客、YouTube、Bubble 论坛、社交媒体、教程或直接与客户联系。
赚取佣金
在每个推荐用户订阅的生命周期内定期收取佣金。
获得报酬
当余额达到最低阈值时，通过银行转账或 PayPal 请求付款。
准备好让您的应用程序多语言化了吗？
安装免费插件，创建一个项目，粘贴您的 API 密钥 - 您的 Bubble 应用程序会讲每种语言。