feat: 🌍 Add fluent locale() method for localization with

caching.

Author: mikebronner

src/ProviderAndDumperAggregator.php

@@ -34,6 +34,7 @@ class ProviderAndDumperAggregator
     protected $limit;
     protected $results;
     protected $isCaching = true;
+    protected ?string $locale = null;
 
     public function __construct()
     {
@@ -98,12 +99,23 @@ public function dump(string $dumper) : Collection
 
     public function geocode(string $value) : self
     {
+        if ($this->locale !== null) {
+            return $this->geocodeQuery(GeocodeQuery::create($value)->withLocale($this->locale));
+        }
+
         $cacheKey = (new Str)->slug(strtolower(urlencode($value)));
         $this->results = $this->cacheRequest($cacheKey, [$value], "geocode");
 
         return $this;
     }
 
+    public function locale(?string $locale) : self
+    {
+        $this->locale = $locale;
+
+        return $this;
+    }
+
     public function geocodeQuery(GeocodeQuery $query) : self
     {
         $cacheKey = serialize($query);
@@ -169,6 +181,12 @@ public function registerProvidersFromConfig(Collection $providers) : self
 
     public function reverse(float $latitude, float $longitude) : self
     {
+        if ($this->locale !== null) {
+            return $this->reverseQuery(
+                ReverseQuery::fromCoordinates($latitude, $longitude)->withLocale($this->locale)
+            );
+        }
+
         $cacheKey = strtolower(urlencode("{$latitude}-{$longitude}"));
         $this->results = $this->cacheRequest($cacheKey, [$latitude, $longitude], "reverse");
 

tests/Feature/Providers/GeocoderServiceTest.php

@@ -292,6 +292,50 @@
     Http::assertSent(fn ($request) => $request->header('User-Agent')[0] === 'ContainerBoundAgent/1.0');
 });
 
+it('propagates locale via the fluent locale() method on geocode()', function () {
+    app('geocoder')
+        ->locale('it')
+        ->geocode('1600 Pennsylvania Ave NW, Washington, DC 20500, USA')
+        ->get();
+
+    Http::assertSent(fn ($request) => str_contains($request->url(), 'accept-language=it'));
+});
+
+it('propagates locale via the fluent locale() method on reverse()', function () {
+    app('geocoder')
+        ->locale('fr')
+        ->reverse(38.8791981, -76.9818437)
+        ->get();
+
+    Http::assertSent(fn ($request) =>
+        str_contains($request->url(), '/reverse')
+        && str_contains($request->url(), 'accept-language=fr')
+    );
+});
+
+it('caches locale-scoped convenience-method results separately per locale', function () {
+    app('geocoder')->locale('it')->geocode('Washington')->get();
+    app('geocoder')->locale('fr')->geocode('Washington')->get();
+    app('geocoder')->locale('it')->geocode('Washington')->get();
+
+    Http::assertSentCount(2);
+});
+
+it('propagates locale from geocodeQuery to the provider and caches per-locale', function () {
+    $italianQuery = GeocodeQuery::create('1600 Pennsylvania Ave NW, Washington, DC 20500, USA')
+        ->withLocale('it');
+    $frenchQuery = GeocodeQuery::create('1600 Pennsylvania Ave NW, Washington, DC 20500, USA')
+        ->withLocale('fr');
+
+    app('geocoder')->geocodeQuery($italianQuery)->get();
+    app('geocoder')->geocodeQuery($frenchQuery)->get();
+    app('geocoder')->geocodeQuery($italianQuery)->get();
+
+    Http::assertSent(fn ($request) => str_contains($request->url(), 'accept-language=it'));
+    Http::assertSent(fn ($request) => str_contains($request->url(), 'accept-language=fr'));
+    Http::assertSentCount(2);
+});
+
 it('does not collide reverse cache keys across coordinate signs', function () {
     $providerName = app('geocoder')->getProvider()->getName();
     $negativeKey = sha1("{$providerName}-" . strtolower(urlencode('-45.473282--73.834721')));