@tomako/tools-runtime 0.1.0

package/src/features/tools/utm-builder/utm-builder.package.ts

@@ -0,0 +1,846 @@
+import type { AppLocale } from "../../../i18n/locale";
+import { z } from "zod";
+
+import type { ToolPackage } from "../package/types";
+
+/**
+ * UTM Builder（instant 车道首个正式工具）。
+ * 证据：docs/seo-keyword-briefs/utm-builder.md（utm builder 12,100/mo LOW + 竞品拆解）。
+ * 反超点（相对 ga-dev-tools / utmbuilder.net / dashthis / tilda）：
+ * 输入自动规范化（空格→连字符、可选小写归一、已有 utm 参数覆盖警告、协议自动补全），
+ * 修复项以 warnings 显式输出；URL 纯浏览器本地计算，不上传服务器。
+ */
+const resultSchema = z.object({
+  finalUrl: z.string().min(1),
+  params: z.object({
+    source: z.string().min(1),
+    medium: z.string().min(1),
+    campaign: z.string().min(1),
+    term: z.string().optional(),
+    content: z.string().optional(),
+  }),
+  warnings: z.array(z.string()),
+});
+
+const UTM_KEYS = ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"] as const;
+
+type WarnLocale = "en" | "zh" | "zh-tw";
+
+const WARN_TEXT: Record<string, Record<WarnLocale, string>> = {
+  schemeAdded: {
+    en: "The destination URL had no protocol, so https:// was added automatically.",
+    zh: "目标 URL 缺少协议，已自动补全 https:// 前缀。",
+    "zh-tw": "目標 URL 缺少協定，已自動補全 https:// 前綴。",
+  },
+  existingUtmReplaced: {
+    en: "The URL already contained UTM parameters ({keys}); they were replaced with your new values.",
+    zh: "URL 中已存在 UTM 参数（{keys}），已用你填写的新值覆盖。",
+    "zh-tw": "URL 中已存在 UTM 參數（{keys}），已用你填寫的新值覆蓋。",
+  },
+  spacesReplaced: {
+    en: "Spaces in {field} were replaced with hyphens so analytics tools read one clean value.",
+    zh: "{field} 中的空格已替换为连字符，避免统计工具把值截断。",
+    "zh-tw": "{field} 中的空格已替換為連字號，避免統計工具把值截斷。",
+  },
+  lowercased: {
+    en: "Uppercase letters in {field} were converted to lowercase to keep report values consistent (google ≠ Google in GA4).",
+    zh: "{field} 中的大写字母已转为小写，避免报表把 google 和 Google 统计成两个渠道。",
+    "zh-tw": "{field} 中的大寫字母已轉為小寫，避免報表把 google 和 Google 統計成兩個管道。",
+  },
+  fragmentKept: {
+    en: "The #fragment was kept at the very end of the URL, after all UTM parameters.",
+    zh: "URL 中的 # 锚点已保留在最末尾，UTM 参数插在它之前。",
+    "zh-tw": "URL 中的 # 錨點已保留在最末尾，UTM 參數插在它之前。",
+  },
+};
+
+const FIELD_NAME: Record<string, Record<WarnLocale, string>> = {
+  source: { en: "utm_source", zh: "utm_source", "zh-tw": "utm_source" },
+  medium: { en: "utm_medium", zh: "utm_medium", "zh-tw": "utm_medium" },
+  campaign: { en: "utm_campaign", zh: "utm_campaign", "zh-tw": "utm_campaign" },
+  term: { en: "utm_term", zh: "utm_term", "zh-tw": "utm_term" },
+  content: { en: "utm_content", zh: "utm_content", "zh-tw": "utm_content" },
+};
+
+function toWarnLocale(locale: AppLocale): WarnLocale {
+  if (locale === "en") return "en";
+  if (locale === "zh-tw") return "zh-tw";
+  return "zh";
+}
+
+function warn(key: keyof typeof WARN_TEXT, locale: AppLocale, vars?: Record<string, string>): string {
+  const l = toWarnLocale(locale);
+  let text = WARN_TEXT[key][l];
+  if (vars) {
+    for (const [name, value] of Object.entries(vars)) {
+      text = text.replace(`{${name}}`, value);
+    }
+  }
+  return text;
+}
+
+export const utmBuilderPackage: ToolPackage = {
+  meta: {
+    slug: "utm-builder",
+    toolType: "generator",
+    keywordEvidence: "docs/seo-keyword-briefs/utm-builder.md",
+    seo: {
+      updatedAt: "2026-07-04",
+      readingTime: "6 min",
+      ogImage: "/tools/utm-builder-hero.webp",
+    },
+  },
+  copy: {
+    title: { en: "UTM Builder", zh: "UTM 链接生成器", "zh-tw": "UTM 連結生成器" },
+    description: {
+      en: "Free UTM builder and campaign URL generator: add utm_source, utm_medium, and utm_campaign to any link and get a clean, trackable URL for GA4 — auto-normalized, built entirely in your browser.",
+      zh: "免费 UTM 链接生成器：填写目标 URL 和来源、媒介、活动名，立即得到兼容 GA4 的追踪链接。输入自动规范化，全部在浏览器本地完成。",
+      "zh-tw": "免費 UTM 連結生成器：填寫目標 URL 和來源、媒介、活動名，立即得到兼容 GA4 的追蹤連結。輸入自動規範化，全部在瀏覽器本地完成。",
+    },
+    intro: {
+      en: "Hand-editing campaign URLs breaks tracking: a second question mark, a stray space, or Google vs google splits your GA4 reports. This UTM generator validates the URL, normalizes every parameter, and tells you exactly what it fixed.",
+      zh: "手拼追踪链接很容易翻车：多一个问号、混入空格、大小写不一致，GA4 报表就会把同一渠道拆成两条。这个 UTM 生成器会校验 URL、规范化每个参数，并明确告诉你修复了什么。",
+      "zh-tw":
+        "手拼追蹤連結很容易出錯：多一個問號、混入空格、大小寫不一致，GA4 報表就會把同一管道拆成兩條。這個 UTM 生成器會校驗 URL、規範化每個參數，並明確告訴你修復了什麼。",
+    },
+    category: {
+      en: "Marketing tools",
+      zh: "营销工具",
+      "zh-tw": "行銷工具",
+    },
+    keywords: {
+      en: ["utm builder", "utm generator", "utm maker", "campaign url builder", "utm code generator", "utm link builder", "utm url builder", "free utm builder", "google utm builder"],
+      zh: ["UTM 链接生成器", "UTM 参数生成", "UTM 制作工具", "营销活动链接生成", "UTM 追踪代码", "UTM 追踪链接", "UTM URL 生成", "免费 UTM 工具", "GA4 UTM"],
+      "zh-tw": ["UTM 連結生成器", "UTM 參數生成", "UTM 製作工具", "行銷活動連結生成", "UTM 追蹤代碼", "UTM 追蹤連結", "UTM URL 生成", "免費 UTM 工具", "GA4 UTM"],
+    },
+    inputSignal: {
+      en: "Destination URL + source / medium / campaign",
+      zh: "目标 URL + 来源 / 媒介 / 活动名",
+      "zh-tw": "目標 URL + 來源 / 媒介 / 活動名",
+    },
+    outputSignal: {
+      en: "Copy-ready campaign URL + auto-fix notes",
+      zh: "可直接复制的追踪链接 + 自动修复说明",
+      "zh-tw": "可直接複製的追蹤連結 + 自動修復說明",
+    },
+    boundarySignal: {
+      en: "Builds and normalizes links locally; it does not shorten URLs or report clicks",
+      zh: "本地生成并规范化链接；不做短链，也不统计点击",
+      "zh-tw": "本地生成並規範化連結；不做短鏈，也不統計點擊",
+    },
+  },
+  form: [
+    {
+      kind: "text",
+      id: "websiteUrl",
+      required: true,
+      minLength: 4,
+      fullWidth: true,
+      label: { en: "Destination URL", zh: "目标 URL", "zh-tw": "目標 URL" },
+      hint: {
+        en: "The landing page the ad, email, or post should open",
+        zh: "广告、邮件或帖子要打开的落地页",
+        "zh-tw": "廣告、郵件或貼文要打開的到達網頁",
+      },
+      placeholder: { en: "https://tomako.ai/pricing", zh: "https://tomako.ai/pricing", "zh-tw": "https://tomako.ai/pricing" },
+      invalidMessage: {
+        en: "Paste the full landing page URL, e.g. https://example.com/pricing.",
+        zh: "请粘贴完整的落地页 URL，例如 https://example.com/pricing。",
+        "zh-tw": "請貼上完整的到達網頁 URL，例如 https://example.com/pricing。",
+      },
+    },
+    {
+      kind: "text",
+      id: "source",
+      required: true,
+      label: { en: "Campaign source (utm_source)", zh: "流量来源 utm_source", "zh-tw": "流量來源 utm_source" },
+      hint: {
+        en: "Where the traffic comes from",
+        zh: "流量从哪个平台来",
+        "zh-tw": "流量從哪個平台來",
+      },
+      placeholder: { en: "google / newsletter / twitter", zh: "google / newsletter / twitter", "zh-tw": "google / newsletter / twitter" },
+      invalidMessage: {
+        en: "Name the traffic source, e.g. google, newsletter, or twitter.",
+        zh: "请填写流量来源，例如 google、newsletter 或 twitter。",
+        "zh-tw": "請填寫流量來源，例如 google、newsletter 或 twitter。",
+      },
+    },
+    {
+      kind: "text",
+      id: "medium",
+      required: true,
+      label: { en: "Campaign medium (utm_medium)", zh: "营销媒介 utm_medium", "zh-tw": "行銷媒介 utm_medium" },
+      hint: {
+        en: "Use GA4-recognized values so traffic lands in the right channel group: cpc, email, social, referral, display, affiliate",
+        zh: "建议用 GA4 渠道分组认可的标准值：cpc、email、social、referral、display、affiliate",
+        "zh-tw": "建議用 GA4 管道群組認可的標準值：cpc、email、social、referral、display、affiliate",
+      },
+      placeholder: { en: "cpc / email / social", zh: "cpc / email / social", "zh-tw": "cpc / email / social" },
+      invalidMessage: {
+        en: "Name the channel type, e.g. cpc, email, or social.",
+        zh: "请填写渠道类型，例如 cpc、email 或 social。",
+        "zh-tw": "請填寫管道類型，例如 cpc、email 或 social。",
+      },
+    },
+    {
+      kind: "text",
+      id: "campaign",
+      required: true,
+      label: { en: "Campaign name (utm_campaign)", zh: "活动名称 utm_campaign", "zh-tw": "活動名稱 utm_campaign" },
+      hint: {
+        en: "What this push is called in reports",
+        zh: "这次投放在报表里叫什么",
+        "zh-tw": "這次投放在報表裡叫什麼",
+      },
+      placeholder: { en: "summer-sale", zh: "summer-sale", "zh-tw": "summer-sale" },
+      invalidMessage: {
+        en: "Name the campaign, e.g. summer-sale or launch-week.",
+        zh: "请填写活动名称，例如 summer-sale 或 launch-week。",
+        "zh-tw": "請填寫活動名稱，例如 summer-sale 或 launch-week。",
+      },
+    },
+    {
+      kind: "text",
+      id: "term",
+      advanced: true,
+      label: { en: "Paid keyword (utm_term, optional)", zh: "付费关键词 utm_term（选填）", "zh-tw": "付費關鍵詞 utm_term（選填）" },
+      hint: {
+        en: "Only for paid search: the keyword you bid on",
+        zh: "只在付费搜索时填：你出价的关键词",
+        "zh-tw": "只在付費搜尋時填：你出價的關鍵詞",
+      },
+      placeholder: { en: "running-shoes", zh: "running-shoes", "zh-tw": "running-shoes" },
+    },
+    {
+      kind: "text",
+      id: "content",
+      advanced: true,
+      label: { en: "Ad / link variant (utm_content, optional)", zh: "素材版本 utm_content（选填）", "zh-tw": "素材版本 utm_content（選填）" },
+      hint: {
+        en: "Tells two creatives or link positions apart in the same campaign",
+        zh: "区分同一活动里的不同素材或链接位置",
+        "zh-tw": "區分同一活動裡的不同素材或連結位置",
+      },
+      placeholder: { en: "hero-banner", zh: "hero-banner", "zh-tw": "hero-banner" },
+    },
+    {
+      kind: "toggle",
+      id: "lowercase",
+      advanced: true,
+      defaultValue: true,
+      label: { en: "Force lowercase values", zh: "参数统一小写", "zh-tw": "參數統一小寫" },
+      hint: {
+        en: "Recommended: GA4 treats Google and google as two different sources",
+        zh: "建议开启：GA4 会把 Google 和 google 当成两个来源",
+        "zh-tw": "建議開啟：GA4 會把 Google 和 google 當成兩個來源",
+      },
+      onLabel: { en: "On", zh: "开启", "zh-tw": "開啟" },
+      offLabel: { en: "Off", zh: "关闭", "zh-tw": "關閉" },
+    },
+  ],
+  runtime: {
+    lane: "instant",
+    compute: (values, locale) => {
+      const warnings: string[] = [];
+
+      let rawUrl = String(values.websiteUrl ?? "").trim();
+      const hasScheme = /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(rawUrl);
+      if (!hasScheme) {
+        rawUrl = `https://${rawUrl}`;
+        warnings.push(warn("schemeAdded", locale));
+      }
+
+      let url: URL;
+      try {
+        url = new URL(rawUrl);
+      } catch {
+        throw new Error("invalid destination URL");
+      }
+      if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("unsupported protocol");
+      }
+      if (!url.hostname.includes(".") && url.hostname !== "localhost") {
+        throw new Error("hostname looks incomplete");
+      }
+
+      const replacedKeys = UTM_KEYS.filter((key) => url.searchParams.has(key));
+      if (replacedKeys.length > 0) {
+        warnings.push(warn("existingUtmReplaced", locale, { keys: replacedKeys.join(", ") }));
+        for (const key of replacedKeys) url.searchParams.delete(key);
+      }
+
+      const forceLowercase = values.lowercase !== false;
+      const spacesFixed: string[] = [];
+      const caseFixed: string[] = [];
+      const fieldLocale = toWarnLocale(locale);
+
+      const normalize = (field: keyof typeof FIELD_NAME, raw: unknown): string => {
+        let value = String(raw ?? "").trim();
+        if (!value) return "";
+        if (/\s/.test(value)) {
+          value = value.replace(/\s+/g, "-");
+          spacesFixed.push(FIELD_NAME[field][fieldLocale]);
+        }
+        if (forceLowercase && /[A-Z]/.test(value)) {
+          value = value.toLowerCase();
+          caseFixed.push(FIELD_NAME[field][fieldLocale]);
+        }
+        return value;
+      };
+
+      const params = {
+        source: normalize("source", values.source),
+        medium: normalize("medium", values.medium),
+        campaign: normalize("campaign", values.campaign),
+        term: normalize("term", values.term) || undefined,
+        content: normalize("content", values.content) || undefined,
+      };
+
+      if (spacesFixed.length > 0) {
+        warnings.push(warn("spacesReplaced", locale, { field: spacesFixed.join(", ") }));
+      }
+      if (caseFixed.length > 0) {
+        warnings.push(warn("lowercased", locale, { field: caseFixed.join(", ") }));
+      }
+
+      url.searchParams.set("utm_source", params.source);
+      url.searchParams.set("utm_medium", params.medium);
+      url.searchParams.set("utm_campaign", params.campaign);
+      if (params.term) url.searchParams.set("utm_term", params.term);
+      if (params.content) url.searchParams.set("utm_content", params.content);
+
+      if (url.hash) {
+        warnings.push(warn("fragmentKept", locale));
+      }
+
+      return {
+        finalUrl: url.toString(),
+        params,
+        warnings,
+      };
+    },
+  },
+  resultSchema,
+  resultView: [
+    {
+      block: "keyValues",
+      title: { en: "Your campaign URL", zh: "你的追踪链接", "zh-tw": "你的追蹤連結" },
+      items: [
+        {
+          label: { en: "Tracking link", zh: "UTM 链接", "zh-tw": "UTM 連結" },
+          path: "finalUrl",
+          copyable: true,
+        },
+      ],
+    },
+    {
+      block: "keyValues",
+      title: { en: "Parameter breakdown", zh: "参数逐项预览", "zh-tw": "參數逐項預覽" },
+      items: [
+        { label: { en: "utm_source", zh: "utm_source", "zh-tw": "utm_source" }, path: "params.source" },
+        { label: { en: "utm_medium", zh: "utm_medium", "zh-tw": "utm_medium" }, path: "params.medium" },
+        { label: { en: "utm_campaign", zh: "utm_campaign", "zh-tw": "utm_campaign" }, path: "params.campaign" },
+        { label: { en: "utm_term", zh: "utm_term", "zh-tw": "utm_term" }, path: "params.term" },
+        { label: { en: "utm_content", zh: "utm_content", "zh-tw": "utm_content" }, path: "params.content" },
+      ],
+    },
+    {
+      block: "bulletList",
+      title: { en: "Auto-fixes applied", zh: "自动修复说明", "zh-tw": "自動修復說明" },
+      path: "warnings",
+      tone: "risk",
+    },
+  ],
+  widget: {
+    formTitle: { en: "Build a trackable campaign link", zh: "生成可追踪的活动链接", "zh-tw": "生成可追蹤的活動連結" },
+    formHint: {
+      en: "Fill in the destination URL and where the link will run. The tracking link is generated instantly in your browser — the URL never leaves this page.",
+      zh: "填写落地页 URL 和投放位置，追踪链接会在浏览器里即时生成——URL 不会被上传到任何服务器。",
+      "zh-tw": "填寫到達網頁 URL 和投放位置，追蹤連結會在瀏覽器裡即時生成——URL 不會被上傳到任何伺服器。",
+    },
+    submitLabel: { en: "Generate UTM link", zh: "生成 UTM 链接", "zh-tw": "生成 UTM 連結" },
+    resultTitle: { en: "Copy your tracking link", zh: "复制你的追踪链接", "zh-tw": "複製你的追蹤連結" },
+    errorOverrides: {
+      computeFailed: {
+        title: { en: "Check the destination URL", zh: "请检查目标 URL", "zh-tw": "請檢查目標 URL" },
+        body: {
+          en: "The destination URL could not be parsed. Use a full web address like https://example.com/pricing — other protocols such as mailto: or ftp: are not supported.",
+          zh: "目标 URL 无法解析。请使用完整的网页地址，例如 https://example.com/pricing；不支持 mailto:、ftp: 等其他协议。",
+          "zh-tw": "目標 URL 無法解析。請使用完整的網址，例如 https://example.com/pricing；不支援 mailto:、ftp: 等其他協定。",
+        },
+      },
+    },
+  },
+  page: {
+    workspace: {
+      heading: {
+        en: "Tag the link before you launch the campaign",
+        zh: "投放前先给链接打上追踪参数",
+        "zh-tw": "投放前先給連結打上追蹤參數",
+      },
+      hint: {
+        en: "Enter the landing page and name the source, medium, and campaign. You get a copy-ready campaign URL with every parameter validated, normalized, and explained — no sign-up, no waiting.",
+        zh: "填写落地页地址，写清来源、媒介和活动名，立即得到可复制的追踪链接；每个参数都会被校验、规范化并说明修复原因。无需注册，无需等待。",
+        "zh-tw": "填寫到達網頁的網址，寫清來源、媒介和活動名，立即得到可複製的追蹤連結；每個參數都會被校驗、規範化並說明修復原因。無需註冊，無需等待。",
+      },
+      badge: { en: "Instant result", zh: "即时生成", "zh-tw": "即時生成" },
+    },
+    sections: [
+      {
+        kind: "cards",
+        heading: {
+          en: "What you get from this UTM generator",
+          zh: "这个 UTM 生成器会给你什么",
+          "zh-tw": "這個 UTM 生成器會給你什麼",
+        },
+        items: [
+          {
+            title: { en: "A copy-ready tracking link", zh: "可直接复制的追踪链接", "zh-tw": "可直接複製的追蹤連結" },
+            body: {
+              en: "One click copies the final campaign URL, ready to paste into Google Ads, a newsletter, or a social post.",
+              zh: "一键复制最终链接，直接粘贴到 Google Ads、邮件或社媒帖子里投放。",
+              "zh-tw": "一鍵複製最終連結，直接貼上到 Google Ads、郵件或社群貼文裡投放。",
+            },
+          },
+          {
+            title: { en: "Parameter-by-parameter preview", zh: "参数逐项预览", "zh-tw": "參數逐項預覽" },
+            body: {
+              en: "See the final utm_source, utm_medium, utm_campaign, utm_term, and utm_content values so the team can check naming consistency before launch.",
+              zh: "逐项展示 utm_source、utm_medium、utm_campaign、utm_term、utm_content 的最终值，团队投放前核对命名是否一致。",
+              "zh-tw": "逐項展示 utm_source、utm_medium、utm_campaign、utm_term、utm_content 的最終值，團隊投放前核對命名是否一致。",
+            },
+          },
+          {
+            title: { en: "Auto-fix notes, not silent edits", zh: "显式的自动修复说明", "zh-tw": "顯式的自動修復說明" },
+            body: {
+              en: "Spaces become hyphens, uppercase becomes lowercase, existing UTM tags get replaced — and every fix is listed so nothing changes behind your back.",
+              zh: "空格转连字符、大写转小写、旧 UTM 参数被覆盖——每一处修复都会列出来，不做暗改。",
+              "zh-tw": "空格轉連字號、大寫轉小寫、舊 UTM 參數被覆蓋——每一處修復都會列出來，不做暗改。",
+            },
+          },
+          {
+            title: { en: "A URL that stays valid", zh: "结构始终正确的 URL", "zh-tw": "結構始終正確的 URL" },
+            body: {
+              en: "Only one question mark, existing query strings preserved, #fragments kept at the end — the structural mistakes that break hand-built links are handled for you.",
+              zh: "只有一个问号、原有查询参数保留、# 锚点保持在末尾——手拼链接最常见的结构错误都被自动处理。",
+              "zh-tw": "只有一個問號、原有查詢參數保留、# 錨點保持在末尾——手拼連結最常見的結構錯誤都被自動處理。",
+            },
+          },
+        ],
+      },
+      {
+        kind: "cards",
+        heading: {
+          en: "What each UTM parameter means",
+          zh: "5 个 UTM 参数分别是什么",
+          "zh-tw": "5 個 UTM 參數分別是什麼",
+        },
+        items: [
+          {
+            title: { en: "utm_source — where", zh: "utm_source——从哪来", "zh-tw": "utm_source——從哪來" },
+            body: {
+              en: "The platform sending the traffic: google, newsletter, twitter. Required, and the first thing GA4 shows in acquisition reports.",
+              zh: "带来流量的平台：google、newsletter、twitter。必填，也是 GA4 流量获取报告里的第一列。",
+              "zh-tw": "帶來流量的平台：google、newsletter、twitter。必填，也是 GA4 流量獲取報告裡的第一欄。",
+            },
+          },
+          {
+            title: { en: "utm_medium — how", zh: "utm_medium——什么渠道", "zh-tw": "utm_medium——什麼管道" },
+            body: {
+              en: "The channel type: cpc for paid search, email, social, referral. GA4's default channel grouping matches on these exact values.",
+              zh: "渠道类型：付费搜索用 cpc，还有 email、social、referral。GA4 的默认渠道分组按这些标准值精确匹配。",
+              "zh-tw": "管道類型：付費搜尋用 cpc，還有 email、social、referral。GA4 的預設管道群組按這些標準值精確匹配。",
+            },
+          },
+          {
+            title: { en: "utm_campaign — which push", zh: "utm_campaign——哪次投放", "zh-tw": "utm_campaign——哪次投放" },
+            body: {
+              en: "The name of this specific promotion: launch-week-2026, summer-sale. Specific enough that you can still find it next quarter.",
+              zh: "这次投放的名字：launch-week-2026、summer-sale。要具体到下个季度还能找到它。",
+              "zh-tw": "這次投放的名字：launch-week-2026、summer-sale。要具體到下個季度還能找到它。",
+            },
+          },
+          {
+            title: { en: "utm_term — which keyword", zh: "utm_term——哪个关键词", "zh-tw": "utm_term——哪個關鍵詞" },
+            body: {
+              en: "Optional, for paid search only: the keyword you bid on, like running-shoes. Skip it for email and social links.",
+              zh: "选填，仅用于付费搜索：你出价的关键词，例如 running-shoes。邮件和社媒链接不需要填。",
+              "zh-tw": "選填，僅用於付費搜尋：你出價的關鍵詞，例如 running-shoes。郵件和社群連結不需要填。",
+            },
+          },
+          {
+            title: { en: "utm_content — which variant", zh: "utm_content——哪个版本", "zh-tw": "utm_content——哪個版本" },
+            body: {
+              en: "Optional: tells two creatives or link positions apart in the same campaign, like hero-banner vs footer-link, for A/B comparisons.",
+              zh: "选填：区分同一活动里的不同素材或链接位置，例如 hero-banner 和 footer-link，用于 A/B 对比。",
+              "zh-tw": "選填：區分同一活動裡的不同素材或連結位置，例如 hero-banner 和 footer-link，用於 A/B 對比。",
+            },
+          },
+        ],
+      },
+      {
+        kind: "bullets",
+        heading: {
+          en: "When you need a campaign URL builder",
+          zh: "什么时候需要活动链接生成器",
+          "zh-tw": "什麼時候需要活動連結生成器",
+        },
+        image: {
+          src: "/tools/utm-builder-support.webp",
+          alt: {
+            en: "Illustration of a marketer tagging links for ads, email, and social channels before a campaign launch.",
+            zh: "营销人员在活动上线前为广告、邮件和社媒渠道的链接打追踪参数的插画。",
+            "zh-tw": "行銷人員在活動上線前為廣告、郵件和社群管道的連結打追蹤參數的插畫。",
+          },
+          side: "right",
+          wide: true,
+        },
+        groups: [
+          {
+            items: {
+              en: [
+                "You are launching paid ads and need GA4 to attribute traffic to the right source and medium, like google / cpc.",
+                "You send newsletters and want email clicks separated from direct traffic instead of disappearing into (direct).",
+                "You post the same link on Twitter, LinkedIn, and communities and want to know which channel actually converts.",
+                "You run partner or influencer promotions and need each collaboration tracked with its own campaign name.",
+                "You print QR codes on offline material and want scans to show up as a measurable campaign.",
+              ],
+              zh: [
+                "你要投付费广告，需要 GA4 把流量正确归因到来源和媒介，比如 google / cpc。",
+                "你在发邮件 newsletter，想让邮件点击和直接访问分开，而不是全部混进 (direct)。",
+                "同一个链接要发 Twitter、LinkedIn 和社区，你想知道到底哪个渠道真的带来转化。",
+                "你在做合作推广或 KOL 投放，每个合作方需要独立的活动名来追踪效果。",
+                "你要在线下物料上印二维码，希望扫码流量也能作为可度量的活动出现在报表里。",
+              ],
+              "zh-tw": [
+                "你要投付費廣告，需要 GA4 把流量正確歸因到來源和媒介，比如 google / cpc。",
+                "你在發郵件 newsletter，想讓郵件點擊和直接訪問分開，而不是全部混進 (direct)。",
+                "同一個連結要發 Twitter、LinkedIn 和社群，你想知道到底哪個管道真的帶來轉化。",
+                "你在做合作推廣或 KOL 投放，每個合作方需要獨立的活動名來追蹤效果。",
+                "你要在線下物料上印 QR Code，希望掃碼流量也能作為可度量的活動出現在報表裡。",
+              ],
+            },
+          },
+        ],
+      },
+      {
+        kind: "bullets",
+        heading: {
+          en: "What this tool does and does not do",
+          zh: "这个工具做什么、不做什么",
+          "zh-tw": "這個工具做什麼、不做什麼",
+        },
+        image: {
+          src: "/tools/utm-builder-standard.webp",
+          alt: {
+            en: "Illustration of a clean tracking link passing checkpoints for structure, casing, and parameter consistency.",
+            zh: "追踪链接通过结构、大小写和参数一致性检查点的插画。",
+            "zh-tw": "追蹤連結通過結構、大小寫和參數一致性檢查點的插畫。",
+          },
+          side: "left",
+          wide: true,
+        },
+        groups: [
+          {
+            title: { en: "Supported", zh: "支持范围", "zh-tw": "支援範圍" },
+            items: {
+              en: [
+                "Any http or https landing page, including URLs that already carry other query parameters or a #fragment.",
+                "All five standard UTM parameters recognized by GA4, Google Ads, Mixpanel, Matomo, and most analytics tools.",
+                "Auto-normalization: protocol completion, space-to-hyphen, optional lowercase, and replacement of existing UTM tags with a warning.",
+                "Everything is computed locally in your browser — the URL is never uploaded, stored, or logged.",
+              ],
+              zh: [
+                "任何 http 或 https 落地页，包括已带其他查询参数或 # 锚点的 URL。",
+                "GA4、Google Ads、Mixpanel、Matomo 等主流统计工具都识别的 5 个标准 UTM 参数。",
+                "自动规范化：协议补全、空格转连字符、可选小写归一、覆盖旧 UTM 参数并给出警告。",
+                "全部在浏览器本地计算——URL 不会被上传、存储或记录。",
+              ],
+              "zh-tw": [
+                "任何 http 或 https 到達網頁，包括已帶其他查詢參數或 # 錨點的 URL。",
+                "GA4、Google Ads、Mixpanel、Matomo 等主流統計工具都識別的 5 個標準 UTM 參數。",
+                "自動規範化：協定補全、空格轉連字號、可選小寫歸一、覆蓋舊 UTM 參數並給出警告。",
+                "全部在瀏覽器本地計算——URL 不會被上傳、儲存或記錄。",
+              ],
+            },
+          },
+          {
+            title: { en: "Not included", zh: "暂不支持", "zh-tw": "暫不支援" },
+            items: {
+              en: [
+                "It does not shorten links — paste the result into your usual shortener if a campaign needs a short URL.",
+                "It does not measure clicks; results show up in GA4 or your analytics tool after the link goes live.",
+                "It does not tag internal links — UTM parameters on links inside your own site overwrite the real traffic source.",
+                "It builds one link at a time; bulk spreadsheet tagging is a different workflow.",
+              ],
+              zh: [
+                "不做短链——需要短链接时，把结果粘贴到你常用的短链工具即可。",
+                "不统计点击数据；链接上线后，效果在 GA4 或你的统计工具里查看。",
+                "不要给站内链接打 UTM——站内跳转带 UTM 会覆盖真实的流量来源。",
+                "一次生成一条链接；批量表格打参数是另一种工作流。",
+              ],
+              "zh-tw": [
+                "不做短網址——需要短連結時，把結果貼上到你常用的短網址工具即可。",
+                "不統計點擊數據；連結上線後，效果在 GA4 或你的統計工具裡查看。",
+                "不要給站內連結打 UTM——站內跳轉帶 UTM 會覆蓋真實的流量來源。",
+                "一次生成一條連結；批量表格打參數是另一種工作流。",
+              ],
+            },
+          },
+          {
+            title: { en: "If generation fails", zh: "生成失败时", "zh-tw": "生成失敗時" },
+            items: {
+              en: [
+                "Check that the destination URL is a full web address; https:// is added automatically, but mailto: and ftp: are rejected.",
+                "Your form input is kept after an error, so fix the URL and generate again — no retyping.",
+                "If a warning says existing UTM tags were replaced, confirm the old values were safe to drop.",
+              ],
+              zh: [
+                "确认目标 URL 是完整网页地址；https:// 会自动补全，但 mailto:、ftp: 会被拒绝。",
+                "出错后表单内容会保留，修正 URL 再点一次生成即可，不用重填。",
+                "如果警告提示旧 UTM 参数被覆盖，请确认旧值确实可以丢弃。",
+              ],
+              "zh-tw": [
+                "確認目標 URL 是完整網址；https:// 會自動補全，但 mailto:、ftp: 會被拒絕。",
+                "出錯後表單內容會保留，修正 URL 再點一次生成即可，不用重填。",
+                "如果警告提示舊 UTM 參數被覆蓋，請確認舊值確實可以丟棄。",
+              ],
+            },
+          },
+        ],
+      },
+      {
+        kind: "bullets",
+        heading: {
+          en: "How to use the tracking link after copying",
+          zh: "复制链接之后怎么用",
+          "zh-tw": "複製連結之後怎麼用",
+        },
+        image: {
+          src: "/tools/utm-builder-result-use.webp",
+          alt: {
+            en: "Illustration of a tagged campaign link flowing into ads, email, and social posts and reporting back into analytics.",
+            zh: "打好参数的活动链接投放到广告、邮件和社媒，并回流到统计报表的插画。",
+            "zh-tw": "打好參數的活動連結投放到廣告、郵件和社群，並回流到統計報表的插畫。",
+          },
+          side: "right",
+          wide: true,
+        },
+        groups: [
+          {
+            items: {
+              en: [
+                "Paste the link into the ad platform, email tool, or social post exactly as generated — do not re-edit it by hand.",
+                "Open the link once yourself and check the GA4 realtime report to confirm source and medium show up correctly.",
+                "Keep one naming convention: always lowercase, always the same channel words (twitter, not tw or Twitter).",
+                "Record the campaign name in your team's tracking sheet so the next launch reuses the same values.",
+                "Need different ad creatives measured separately? Generate one link per variant using utm_content.",
+              ],
+              zh: [
+                "把链接原样粘贴到广告平台、邮件工具或社媒帖子里，不要再手动改动。",
+                "自己先点一次链接，在 GA4 实时报表里确认来源和媒介显示正确。",
+                "保持统一命名：始终小写、渠道词固定（用 twitter，不要 tw 或 Twitter 混用）。",
+                "把活动名记进团队的投放表格，下次投放沿用同一套命名。",
+                "不同广告素材要分开统计时，用 utm_content 为每个版本单独生成链接。",
+              ],
+              "zh-tw": [
+                "把連結原樣貼上到廣告平台、郵件工具或社群貼文裡，不要再手動改動。",
+                "自己先點一次連結，在 GA4 即時報表裡確認來源和媒介顯示正確。",
+                "保持統一命名：始終小寫、管道詞固定（用 twitter，不要 tw 或 Twitter 混用）。",
+                "把活動名記進團隊的投放表格，下次投放沿用同一套命名。",
+                "不同廣告素材要分開統計時，用 utm_content 為每個版本單獨生成連結。",
+              ],
+            },
+          },
+        ],
+      },
+      {
+        kind: "cards",
+        heading: {
+          en: "Why this instead of Google's builder or a spreadsheet",
+          zh: "为什么不用官方工具或表格手拼",
+          "zh-tw": "為什麼不用官方工具或表格手拼",
+        },
+        items: [
+          {
+            title: { en: "It fixes input instead of trusting it", zh: "主动修复输入，而不是照单全收", "zh-tw": "主動修復輸入，而不是照單全收" },
+            body: {
+              en: "Google's Campaign URL Builder and most free UTM makers paste whatever you type. This one normalizes spaces, casing, and duplicate tags, and shows each fix.",
+              zh: "Google 官方 Campaign URL Builder 和多数免费工具会把你输入的内容原样拼上去。这里会规范空格、大小写和重复参数，并把每处修复列出来。",
+              "zh-tw": "Google 官方 Campaign URL Builder 和多數免費工具會把你輸入的內容原樣拼上去。這裡會規範空格、大小寫和重複參數，並把每處修復列出來。",
+            },
+          },
+          {
+            title: { en: "No sign-up, no ads, instant result", zh: "免登录、无广告、即时出结果", "zh-tw": "免登入、無廣告、即時出結果" },
+            body: {
+              en: "No account required, no upsell banners between you and the link. Fill the form, copy the URL, done in under a minute.",
+              zh: "没有注册墙，没有夹在中间的推销横幅。填完表单、复制链接，一分钟内完成。",
+              "zh-tw": "沒有註冊牆，沒有夾在中間的推銷橫幅。填完表單、複製連結，一分鐘內完成。",
+            },
+          },
+          {
+            title: { en: "Private by design", zh: "默认保护你的链接", "zh-tw": "預設保護你的連結" },
+            body: {
+              en: "Unlaunched campaign URLs are sensitive. Everything is computed in your browser, so the link never touches a server.",
+              zh: "未上线的活动链接本身就是敏感信息。所有计算都在浏览器完成，链接不会经过任何服务器。",
+              "zh-tw": "未上線的活動連結本身就是敏感資訊。所有計算都在瀏覽器完成，連結不會經過任何伺服器。",
+            },
+          },
+          {
+            title: { en: "Less error-prone than spreadsheets", zh: "比表格手拼更不容易错", "zh-tw": "比表格手拼更不容易錯" },
+            body: {
+              en: "Spreadsheet formulas silently break URL encoding and produce double question marks. Here the URL structure is parsed and rebuilt properly every time.",
+              zh: "表格公式经常悄悄搞坏 URL 编码或拼出两个问号。这里每次都会真正解析并重建 URL 结构。",
+              "zh-tw": "表格公式經常悄悄搞壞 URL 編碼或拼出兩個問號。這裡每次都會真正解析並重建 URL 結構。",
+            },
+          },
+        ],
+      },
+      {
+        kind: "bullets",
+        heading: {
+          en: "What a good UTM link should look like",
+          zh: "一条好的 UTM 链接长什么样",
+          "zh-tw": "一條好的 UTM 連結長什麼樣",
+        },
+        image: {
+          src: "/tools/utm-builder-value.webp",
+          alt: {
+            en: "Illustration comparing a messy hand-built link with a clean normalized campaign URL.",
+            zh: "手拼的混乱链接与规范化后干净活动链接的前后对比插画。",
+            "zh-tw": "手拼的混亂連結與規範化後乾淨活動連結的前後對比插畫。",
+          },
+          side: "left",
+          wide: true,
+        },
+        groups: [
+          {
+            items: {
+              en: [
+                "One question mark, ampersand-separated parameters, and the #fragment at the very end.",
+                "Lowercase, hyphen-separated values that read the same in every report: utm_source=google, not utm_source=Google%20Ads.",
+                "A campaign name specific enough to find later: launch-week-2026, not test or new.",
+                "source answers where, medium answers how, campaign answers which push — if a value answers the wrong question, rename it.",
+                "The same value spelled the same way across every channel and teammate.",
+              ],
+              zh: [
+                "只有一个问号，参数用 & 分隔，# 锚点保持在最末尾。",
+                "小写、用连字符分隔的参数值，在所有报表里读起来一致：utm_source=google，而不是 utm_source=Google%20Ads。",
+                "活动名要具体到之后能找到：launch-week-2026，而不是 test 或 new。",
+                "source 回答“从哪来”，medium 回答“什么渠道类型”，campaign 回答“哪次投放”——答错问题的值应该改名。",
+                "同一个值在所有渠道、所有同事手里拼写完全一致。",
+              ],
+              "zh-tw": [
+                "只有一個問號，參數用 & 分隔，# 錨點保持在最末尾。",
+                "小寫、用連字號分隔的參數值，在所有報表裡讀起來一致：utm_source=google，而不是 utm_source=Google%20Ads。",
+                "活動名要具體到之後能找到：launch-week-2026，而不是 test 或 new。",
+                "source 回答「從哪來」，medium 回答「什麼管道類型」，campaign 回答「哪次投放」——答錯問題的值應該改名。",
+                "同一個值在所有管道、所有同事手裡拼寫完全一致。",
+              ],
+            },
+          },
+        ],
+      },
+    ],
+    faq: [
+      {
+        question: {
+          en: "What does UTM stand for?",
+          zh: "UTM 是什么的缩写？",
+          "zh-tw": "UTM 是什麼的縮寫？",
+        },
+        answer: {
+          en: "Urchin Tracking Module — named after Urchin, the analytics company Google acquired before building Google Analytics. In practice it means the five utm_ query parameters that tell GA4 where a visit came from; a UTM maker like this one appends them to your URL correctly.",
+          zh: "Urchin Tracking Module 的缩写——Urchin 是 Google 在打造 Google Analytics 之前收购的统计公司。实际含义就是 5 个 utm_ 查询参数，告诉 GA4 一次访问从哪来；这类 UTM 生成工具做的就是把它们正确拼到你的 URL 上。",
+          "zh-tw": "Urchin Tracking Module 的縮寫——Urchin 是 Google 在打造 Google Analytics 之前收購的統計公司。實際含義就是 5 個 utm_ 查詢參數，告訴 GA4 一次訪問從哪來；這類 UTM 生成工具做的就是把它們正確拼到你的 URL 上。",
+        },
+      },
+      {
+        question: {
+          en: "Why were the UTM parameters already in my URL replaced?",
+          zh: "为什么我 URL 里原有的 UTM 参数被覆盖了？",
+          "zh-tw": "為什麼我 URL 裡原有的 UTM 參數被覆蓋了？",
+        },
+        answer: {
+          en: "A URL with two sets of UTM tags produces unpredictable attribution, so the builder keeps exactly one set — the values you just entered — and lists the replaced keys in the auto-fix notes so you can double-check.",
+          zh: "同一条 URL 带两套 UTM 参数会导致归因混乱，所以工具只保留一套（你刚填写的值），并在自动修复说明里列出被覆盖的参数，方便你确认。",
+          "zh-tw": "同一條 URL 帶兩套 UTM 參數會導致歸因混亂，所以工具只保留一套（你剛填寫的值），並在自動修復說明裡列出被覆蓋的參數，方便你確認。",
+        },
+      },
+      {
+        question: {
+          en: "Do these UTM parameters work with GA4?",
+          zh: "生成的 UTM 参数在 GA4 里有效吗？",
+          "zh-tw": "生成的 UTM 參數在 GA4 裡有效嗎？",
+        },
+        answer: {
+          en: "Yes. utm_source, utm_medium, utm_campaign, utm_term, and utm_content are the standard parameters GA4 reads for session and traffic acquisition reports, and the same tags are recognized by Google Ads, Mixpanel, Matomo, and most analytics tools.",
+          zh: "有效。utm_source、utm_medium、utm_campaign、utm_term、utm_content 就是 GA4 会话与流量获取报告读取的标准参数，Google Ads、Mixpanel、Matomo 等工具也识别同一套参数。",
+          "zh-tw": "有效。utm_source、utm_medium、utm_campaign、utm_term、utm_content 就是 GA4 工作階段與流量開發報表讀取的標準參數，Google Ads、Mixpanel、Matomo 等工具也識別同一套參數。",
+        },
+      },
+      {
+        question: {
+          en: "Should UTM values always be lowercase?",
+          zh: "UTM 参数值一定要小写吗？",
+          "zh-tw": "UTM 參數值一定要小寫嗎？",
+        },
+        answer: {
+          en: "Strongly recommended. UTM values are case-sensitive in GA4, so Google and google are counted as two different sources. Keeping everything lowercase is the simplest convention — that is why the lowercase toggle is on by default.",
+          zh: "强烈建议。GA4 里 UTM 值区分大小写，Google 和 google 会被算成两个来源。全小写是最简单可靠的约定，所以“参数统一小写”默认开启。",
+          "zh-tw": "強烈建議。GA4 裡 UTM 值區分大小寫，Google 和 google 會被算成兩個來源。全小寫是最簡單可靠的約定，所以「參數統一小寫」預設開啟。",
+        },
+      },
+      {
+        question: {
+          en: "Is my URL uploaded to a server?",
+          zh: "我的 URL 会被上传到服务器吗？",
+          "zh-tw": "我的 URL 會被上傳到伺服器嗎？",
+        },
+        answer: {
+          en: "No. The link is built entirely in your browser with no network request, so unlaunched campaign URLs, internal domains, and staging links stay on your machine.",
+          zh: "不会。链接完全在浏览器本地生成，不发任何网络请求；未上线的活动链接、内部域名和测试环境地址都不会离开你的电脑。",
+          "zh-tw": "不會。連結完全在瀏覽器本地生成，不發任何網路請求；未上線的活動連結、內部網域和測試環境網址都不會離開你的電腦。",
+        },
+      },
+      {
+        question: {
+          en: "Where should I not use UTM links?",
+          zh: "哪些地方不应该用 UTM 链接？",
+          "zh-tw": "哪些地方不應該用 UTM 連結？",
+        },
+        answer: {
+          en: "Never tag links that point from one page of your site to another. Clicking an internal UTM link starts a new attributed session and overwrites the real traffic source, corrupting your reports.",
+          zh: "不要给站内互相跳转的链接打 UTM。点击站内 UTM 链接会开启新的归因会话，覆盖真实流量来源，直接污染报表数据。",
+          "zh-tw": "不要給站內互相跳轉的連結打 UTM。點擊站內 UTM 連結會開啟新的歸因工作階段，覆蓋真實流量來源，直接污染報表數據。",
+        },
+      },
+    ],
+    cta: {
+      hint: {
+        en: "Link tagged? Put it to work: draft the campaign email that carries it.",
+        zh: "链接打好参数了？下一步：写好承载它的营销邮件。",
+        "zh-tw": "連結打好參數了？下一步：寫好承載它的行銷郵件。",
+      },
+      primary: {
+        href: "/tools/email-template-generator",
+        label: { en: "Draft the campaign email", zh: "生成营销邮件模板", "zh-tw": "生成行銷郵件模板" },
+      },
+      secondary: {
+        href: "/tools",
+        label: { en: "Back to all tools", zh: "返回全部工具", "zh-tw": "返回全部工具" },
+      },
+    },
+  },
+  assets: {
+    hero: {
+      src: "/tools/utm-builder-hero.webp",
+      alt: {
+        en: "Illustration of a campaign link being tagged with UTM parameters and flowing into clean analytics channels.",
+        zh: "活动链接被打上 UTM 参数并汇入清晰流量渠道的插画。",
+        "zh-tw": "活動連結被打上 UTM 參數並匯入清晰流量管道的插畫。",
+      },
+    },
+  },
+};