fix: pass language tag in config

Author: Enter-tainer

apps/docs/contents/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Overview
 createdAt: 2025-07-20T22:35:03+08:00
-lastModified: 2025-11-21T21:25:29+08:00
+lastModified: 2025-11-21T21:41:13+08:00
 ---
 
 # Overview
@@ -135,6 +135,7 @@ This will automatically pull resources from the remote repository, avoiding rebu
 - `mapboxToken`: Mapbox access token (required when using Mapbox provider)
 - `nominatimBaseUrl`: Custom Nominatim base URL (optional, defaults to OpenStreetMap's public instance)
 - `cachePrecision`: Coordinate cache precision (decimals, default: `4`)
+- `language`: Preferred language(s) for results (BCP47, comma-separated or array). Omit to use provider default.
 
 #### System Observability (`system.observability`)
 
@@ -161,6 +162,7 @@ export default defineBuilderConfig(() => ({
     geocodingPlugin({
       enable: true,
       provider: 'nominatim',
+      // language: 'en,zh',
       // Optional: use custom Nominatim instance
       // nominatimBaseUrl: 'https://your-nominatim-instance.com'
     }),
@@ -180,6 +182,7 @@ export default defineBuilderConfig(() => ({
       enable: true,
       provider: 'mapbox',
       mapboxToken: process.env.MAPBOX_TOKEN,
+      // language: 'en-US',
     }),
   ],
 }))

packages/builder/src/photo/README.md

@@ -107,6 +107,7 @@ export default defineBuilderConfig(() => ({
       enable: true,
       provider: 'auto',
       mapboxToken: process.env.MAPBOX_TOKEN,
+      // language: 'en,zh', // 可选，按需设置语言
       // nominatimBaseUrl: 'https://your-nominatim-instance.com',
     }),
   ],

packages/builder/src/photo/geocoding.ts

@@ -163,15 +163,17 @@ export interface GeocodingProvider {
  */
 export class MapboxGeocodingProvider implements GeocodingProvider {
   private readonly accessToken: string
+  private readonly language: string | null
   private readonly baseUrl = 'https://api.mapbox.com'
   private readonly rateLimitMs = 100 // Mapbox 速率限制：1000次/分钟
   private readonly rateLimiter: SequentialRateLimiter
   private readonly interprocessKey: string
   private readonly maxRetries = 3
   private readonly retryBaseDelayMs = 500
 
-  constructor(accessToken: string) {
+  constructor(accessToken: string, language?: string | null) {
     this.accessToken = accessToken
+    this.language = language ?? null
     this.rateLimiter = getGlobalRateLimiter(`mapbox:${accessToken}`, this.rateLimitMs)
     this.interprocessKey = `mapbox:${accessToken}`
   }
@@ -187,8 +189,9 @@ export class MapboxGeocodingProvider implements GeocodingProvider {
         url.searchParams.set('access_token', this.accessToken)
         url.searchParams.set('longitude', lon.toString())
         url.searchParams.set('latitude', lat.toString())
-        url.searchParams.set('types', 'address,place,district,region,country')
-        url.searchParams.set('language', 'zh-Hants')
+        if (this.language) {
+          url.searchParams.set('language', this.language)
+        }
 
         log.info(`调用 Mapbox API: ${lat}, ${lon}`)
 
@@ -266,15 +269,17 @@ export class MapboxGeocodingProvider implements GeocodingProvider {
  */
 export class NominatimGeocodingProvider implements GeocodingProvider {
   private readonly baseUrl: string
+  private readonly language: string | null
   private readonly userAgent = 'afilmory/1.0'
   private readonly rateLimitMs = 1000 // Nominatim 要求至少1秒间隔
   private readonly rateLimiter: SequentialRateLimiter
   private readonly interprocessKey: string
   private readonly maxRetries = 3
   private readonly retryBaseDelayMs = 1000
 
-  constructor(baseUrl?: string) {
+  constructor(baseUrl?: string, language?: string | null) {
     this.baseUrl = baseUrl || 'https://nominatim.openstreetmap.org'
+    this.language = language ?? null
     this.rateLimiter = getGlobalRateLimiter(`nominatim:${this.baseUrl}`, this.rateLimitMs)
     this.interprocessKey = `nominatim:${this.baseUrl}`
   }
@@ -291,13 +296,16 @@ export class NominatimGeocodingProvider implements GeocodingProvider {
         url.searchParams.set('lon', lon.toString())
         url.searchParams.set('format', 'json')
         url.searchParams.set('addressdetails', '1')
-        url.searchParams.set('accept-language', 'zh-CN,zh,en')
+        if (this.language) {
+          url.searchParams.set('accept-language', this.language)
+        }
 
         log.info(`调用 Nominatim API: ${lat}, ${lon}`)
 
         const response = await fetch(url.toString(), {
           headers: {
             'User-Agent': this.userAgent,
+            ...(this.language ? { 'Accept-Language': this.language } : {}),
           },
         })
 
@@ -372,20 +380,22 @@ export class NominatimGeocodingProvider implements GeocodingProvider {
  * @param provider 提供者类型
  * @param mapboxToken Mapbox access token（可选）
  * @param nominatimBaseUrl Nominatim 基础 URL（可选）
+ * @param language 首选语言（可选，逗号分隔的 BCP47 列表）
  */
 export function createGeocodingProvider(
   provider: 'mapbox' | 'nominatim' | 'auto',
   mapboxToken?: string,
   nominatimBaseUrl?: string,
+  language?: string | null,
 ): GeocodingProvider | null {
   // 如果指定了 Mapbox 或自动模式且有 token，使用 Mapbox
   if ((provider === 'mapbox' || provider === 'auto') && mapboxToken) {
-    return new MapboxGeocodingProvider(mapboxToken)
+    return new MapboxGeocodingProvider(mapboxToken, language)
   }
 
   // 使用 Nominatim
   if (provider === 'nominatim' || provider === 'auto') {
-    return new NominatimGeocodingProvider(nominatimBaseUrl)
+    return new NominatimGeocodingProvider(nominatimBaseUrl, language)
   }
 
   return null

packages/builder/src/plugins/geocoding.ts

@@ -21,6 +21,10 @@ interface GeocodingPluginOptions {
   mapboxToken?: string
   nominatimBaseUrl?: string
   cachePrecision?: number
+  /**
+   * Preferred languages for geocoding results (BCP47). Accepts comma-separated string or array.
+   */
+  language?: string | string[]
 }
 type GeocodingPluginOptionsResolved = Required<Pick<GeocodingPluginOptions, 'enable' | 'provider'>> &
   Pick<GeocodingPluginOptions, 'mapboxToken' | 'nominatimBaseUrl' | 'cachePrecision'> & {
@@ -32,6 +36,7 @@ interface ResolvedGeocodingSettings {
   mapboxToken?: string
   nominatimBaseUrl?: string
   cachePrecision: number
+  language: string | null
 }
 
 interface GeocodingState {
@@ -70,6 +75,7 @@ function resolveSettings(options: GeocodingPluginOptions): GeocodingPluginOption
     mapboxToken: options.mapboxToken,
     nominatimBaseUrl: options.nominatimBaseUrl,
     cachePrecision: normalizeCachePrecision(options.cachePrecision ?? DEFAULT_CACHE_PRECISION),
+    language: normalizeLanguage(options.language),
   }
 }
 
@@ -89,7 +95,7 @@ function getOrCreateState(runShared: Map<string, unknown>): GeocodingState {
 }
 
 function buildProviderKey(settings: ResolvedGeocodingSettings): string {
-  return `${settings.provider}:${settings.mapboxToken ?? ''}:${settings.nominatimBaseUrl ?? ''}`
+  return `${settings.provider}:${settings.mapboxToken ?? ''}:${settings.nominatimBaseUrl ?? ''}:${settings.language ?? ''}`
 }
 
 function ensureProvider(
@@ -102,7 +108,16 @@ function ensureProvider(
     return state.provider
   }
 
-  const provider = createGeocodingProvider(settings.provider, settings.mapboxToken, settings.nominatimBaseUrl)
+  if (state.providerKey && state.providerKey !== providerKey) {
+    state.cache.clear()
+  }
+
+  const provider = createGeocodingProvider(
+    settings.provider,
+    settings.mapboxToken,
+    settings.nominatimBaseUrl,
+    settings.language ?? undefined,
+  )
 
   if (!provider) {
     logger.warn('无法创建地理编码提供者，请检查 geocoding 配置和 Token')