多语言支持 | Payve Docs

Payve 支付网关提供完整的多语言支持，让您的客户可以使用他们熟悉的语言完成支付。本文档介绍如何配置和使用多语言功能。

概述

Payve 的多语言系统采用智能语言检测机制，自动为用户展示最合适的语言界面。系统支持以下特性：

🌍 自动语言检测 - 基于用户偏好、浏览器设置和地理位置
🔄 实时切换 - 用户可随时切换界面语言
💾 偏好记忆 - 系统记住用户的语言选择
⚙️ 商户可控 - 商户可以配置支持的语言和默认语言
📱 全平台支持 - 支付页面、邮件通知、API 响应均支持多语言

支持的语言

目前 Payve 支持以下语言：

语言代码	语言名称	覆盖地区
`zh`	中文简体	中国大陆、新加坡
`en`	English	全球
`ja`	日本語	日本 (即将支持)
`ko`	한국어	韩国 (即将支持)

语言检测机制

系统使用以下优先级顺序来确定显示语言：

graph TD
    A[用户访问支付页面] --> B{URL参数有lang?}
    B -->|是| C[使用URL指定语言]
    B -->|否| D{Cookie有偏好?}
    D -->|是| E[使用保存的偏好]
    D -->|否| F{商户设置默认语言?}
    F -->|是| G[使用商户默认语言]
    F -->|否| H{浏览器语言匹配?}
    H -->|是| I[使用浏览器语言]
    H -->|否| J[使用系统默认语言]

1. URL 参数（最高优先级）

通过 URL 参数可以强制指定语言：

https://pay.payve.io/pay/ORDER_ID?lang=zh  # 强制中文
https://pay.payve.io/pay/ORDER_ID?lang=en  # 强制英文

2. 用户偏好（Cookie）

当用户手动切换语言时，选择会保存在 Cookie 中，有效期为一年：

// Cookie 格式
payment-locale=zh; path=/; max-age=31536000

3. 商户默认设置

商户可以在控制台设置默认语言和支持的语言列表。

4. 浏览器语言

系统会读取浏览器的 Accept-Language 头部：

Accept-Language: zh-CN,zh;q=0.9,en;q=0.8

5. 系统默认

如果以上都没有匹配，使用系统默认语言（中文）。

商户配置

通过 API 配置

商户可以通过 API 配置语言设置：

获取当前语言设置

GET /api/v1/merchant/language-settings
Authorization: Bearer YOUR_API_KEY

响应示例：

{
  "success": true,
  "data": {
    "defaultLanguage": "zh",
    "supportedLanguages": ["zh", "en"]
  }
}

更新语言设置

PUT /api/v1/merchant/language-settings
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
 
{
  "defaultLanguage": "en",
  "supportedLanguages": ["en", "zh"]
}

配置参数说明

参数	类型	说明	示例
`defaultLanguage`	string	默认显示语言	`"zh"`
`supportedLanguages`	string[]	支持的语言列表	`["zh", "en"]`

创建支付订单时指定语言

在创建支付订单时，可以指定推荐的显示语言：

POST /api/v1/payments/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
 
{
  "amount": "100.00",
  "currency": "USDT",
  "network": "SOLANA",
  "merchantOrderId": "ORDER_12345",
  "productName": "Premium Plan",
  "metadata": {
    "preferredLanguage": "zh",  # 推荐显示语言
    "userId": "USER_123"
  }
}

BASH

代码已折叠

共 15 行

支付页面多语言

自动适配

支付页面会自动根据语言设置显示相应内容：

页面标题和说明 - 自动翻译
金额和货币 - 根据语言习惯格式化
时间显示 - 本地化时间格式
错误提示 - 本地化错误信息
支付指引 - 本地化操作说明

手动切换

用户可以通过页面右上角的语言选择器切换语言：

<!-- 语言切换器位置 -->
<div class="language-selector">
  <select>
    <option value="zh">中文</option>
    <option value="en">English</option>
  </select>
</div>

Webhook 通知多语言

Webhook 通知中包含语言信息，方便商户处理：

{
  "event": "payment.succeeded",
  "eventId": "evt_abc123",
  "data": {
    "orderId": "ord_xyz789",
    "amount": "100.00",
    "currency": "USDT",
    "language": "zh",  // 用户使用的语言
    "message": {
      "zh": "支付成功",
      "en": "Payment successful"
    }
  }
}

JSON

代码已折叠

共 14 行

邮件通知多语言

系统发送的邮件通知会根据用户语言偏好自动选择模板：

支付成功通知
支付失败通知
订单过期提醒
退款通知

SDK 集成

JavaScript SDK

// 初始化 SDK 时指定语言
const payve = new PayveSDK({
  apiKey: 'YOUR_API_KEY',
  language: 'zh',  // 可选，默认自动检测
});
 
// 创建支付时指定语言
const payment = await payve.createPayment({
  amount: 100,
  currency: 'USDT',
  language: 'zh'  // 可选
});
 
// 获取支付链接（带语言参数）
const paymentUrl = payment.getPaymentUrl('zh');
// 输出: https://pay.payve.io/pay/ORDER_ID?lang=zh

JAVASCRIPT

代码已折叠

共 16 行

React 组件

import { PayvePaymentButton } from '@payve/react';
 
function PaymentPage() {
  return (
    <PayvePaymentButton
      amount="100"
      currency="USDT"
      language="zh"  // 指定语言
      onSuccess={(order) => console.log('支付成功', order)}
      onError={(error) => console.error('支付失败', error)}
    />
  );
}

JSX

代码已折叠

共 13 行

最佳实践

1. 让用户选择

虽然自动检测很智能，但始终提供手动切换选项，让用户可以选择他们偏好的语言。

2. 保持一致性

确保整个支付流程使用同一种语言，包括：

支付页面
邮件通知
错误信息
成功页面

3. 测试多语言

在上线前测试所有支持的语言：

# 测试中文界面
curl https://pay.payve.io/pay/TEST_ORDER?lang=zh
 
# 测试英文界面
curl https://pay.payve.io/pay/TEST_ORDER?lang=en

4. 处理未翻译内容

对于动态内容（如商品名称），建议：

{
  "productName": {
    "zh": "高级会员",
    "en": "Premium Membership"
  }
}

5. 监控语言使用

通过 API 获取语言使用统计：

GET /api/v1/reports/language-stats
Authorization: Bearer YOUR_API_KEY

响应示例：

{
  "success": true,
  "data": {
    "zh": 65,  // 65% 用户使用中文
    "en": 35   // 35% 用户使用英文
  }
}

常见问题

Q: 如何添加新的语言支持？

A: 目前系统支持中文和英文。如需添加其他语言支持，请联系我们的技术支持团队。

Q: 语言设置会影响支付金额吗？

A: 不会。语言设置只影响界面显示，不会改变支付金额、币种或汇率。

Q: 用户的语言偏好会被记录吗？

A: 是的，用户的语言选择会保存在 Cookie 中，下次访问时自动应用。同时，该信息也会记录在订单数据中，方便商户分析。

Q: 如何禁用某种语言？

A: 在商户设置中，将 supportedLanguages 数组中移除不需要的语言即可。

Q: API 响应是否支持多语言？

A: API 响应中的错误信息支持多语言。您可以在请求头中指定 Accept-Language：

GET /api/v1/payments/orders/ORDER_ID
Accept-Language: zh-CN

技术实现

前端技术栈

Next.js - 服务端渲染框架
next-intl - 国际化库
React - UI 框架

语言文件结构

/src/i18n/
├── locales/
│   ├── zh.json      # 中文翻译
│   ├── en.json      # 英文翻译
│   └── ja.json      # 日文翻译（即将支持）
├── request.ts       # 语言检测逻辑
└── config.ts        # i18n 配置

翻译键命名规范

{
  "payment": {
    "title": "支付",
    "amount": "金额",
    "status": {
      "pending": "待支付",
      "completed": "已完成",
      "failed": "失败"
    }
  }
}

JSON

代码已折叠

共 11 行