要在3.4版本Headless-WP-Starter中启用真正全球化，必须同时配置WPML多语言后端与React前端i18next联动：WordPress端需激活WPML及扩展、设置目录结构、注册GraphQL translations字段，并安装WP GraphQL WPML插件；前端需初始化i18next、注入X-WPML-Language请求头、通过页面跳转切换语言以重置GraphQL上下文。
要在3.4版本的Headless-WP-Starter项目中启用真正的全球化能力，必须同时打通WordPress后端多语言内容供给与React前端动态语言切换链路，缺一不可——只配语言包不连GraphQL查询，前端永远拿不到对应语言的数据。
WordPress后端：启用WPML并配置GraphQL多语言端点
第一步：在WordPress后台安装并激活WPML核心插件（SitePress CMS）及String Translation、Translation Management扩展模块。
第二步：进入WPML → Languages → Language configuration，勾选“Different languages in directories”，设置语言目录结构为/en/、/zh/、/ja/等；【必须启用“Duplicate posts for each language”选项，否则ACF字段不会生成对应语言副本】。
第三步：打开wordpress/wp-content/themes/postlight-headless-wp/inc/graphql/，编辑schema.php，在register_post_object()调用后插入以下代码块：
register_graphql_field( 'Post', 'translations', [ 'type' => [ 'list_of' => 'Post' ], 'resolve' => function( $post ) { return apply_filters( 'wpml_post_translations', [], $post->ID ); } ] );
这一步让GraphQL能查到当前文章的所有语言版本ID，是后续前端按locale拉取对应语言内容的前提。
React前端：初始化i18next并绑定GraphQL查询
方法一：基于文件系统的静态语言包加载
在frontend/src/i18n/index.js中创建初始化配置：
import i18n from 'i18next'; import { initReactI18next } from 'react-i18next'; import Backend from 'i18next-http-backend'; import LanguageDetector from 'i18next-browser-languagedetector'; i18n.use(Backend).use(LanguageDetector).use(initReactI18next).init({ fallbackLng: 'en', debug: true, interpolation: { escapeValue: false }, }); export default i18n;
确保frontend/public/locales/en/translation.json和frontend/public/locales/zh/translation.json已存在，且键名与WordPress后台WPML定义的字符串域（text domain）一致，例如"wpml_string_domain"。
方法二：运行时从WordPress REST API动态拉取翻译
在frontend/src/i18n/dynamicLoader.js中编写：
export const loadTranslations = async (lng) => { const res = await fetch(`/wp-json/wpml/v1/strings?lang=${lng}`); return res.json(); };
注意：该API需在WordPress端由WPML或自定义插件暴露，返回格式必须为{ "key": "value" }对象，否则i18next解析失败。
前后端联动：GraphQL查询自动注入当前语言上下文
第一步：在frontend/src/lib/graphqlClient.js中，修改createApolloClient函数：
const httpLink = createHttpLink({ uri: '/graphql', headers: { 'X-WPML-Language': i18n.language || 'en' } });
第二步：在wordpress/wp-content/themes/postlight-headless-wp/inc/graphql/resolvers.php中，为所有post查询添加语言过滤：
add_filter( 'graphql_post_object_query_args', function( $args, $source, $args_input, $info ) { $lang = $_SERVER['HTTP_X_WPML_LANGUAGE'] ?? 'en'; $args['lang'] = $lang; return $args; }, 10, 4 );
第三步：在WordPress端安装WP GraphQL WPML插件（v2.1+），它会自动将WPML语言上下文注入GraphQL解析器，使query { posts(first: 5) { nodes { title excerpt } } }返回当前请求头指定语言的内容，而非默认语言。
这一步不可跳过——没有WP GraphQL WPML插件，即使设置了X-WPML-Language头，GraphQL仍只返回站点默认语言内容。
语言切换器组件：强制刷新页面以重置GraphQL上下文
在frontend/components/LanguageSwitcher.js中写入：
const handleLanguageChange = (e) => { const lang = e.target.value; i18n.changeLanguage(lang); window.location.href = `/${lang}${window.location.pathname.replace(/\/[a-z]{2}\/?/, '')}`; };
使用window.location.href跳转而非history.pushState，是因为Apollo Client缓存和WPML语言上下文均绑定在完整URL路径上，单页跳转无法触发GraphQL重新鉴权与语言重置。
