Czy potrzebuję osobnych subdomen dla każdego języka?

Nie. Trasy oparte na prefiksie języka (/en/, /de/) są prostsze, ponieważ działają ze statycznym hostingiem i są pragmatycznym standardem dla SSG. Subdomeny (en.sklep.com) bywają korzystne pod SEO, ale wymagają konfiguracji DNS i serwera, a zysk rzadko równoważy ten narzut przy stronie statycznej. Dla zdecydowanej większości wielojęzycznych sklepów prefiks jest właściwym wyborem.

Do czego służy tag x-default i czy muszę go dodawać?

x-default wskazuje wersję strony dla użytkowników, których języka nie obsługujesz — to wersja zapasowa dla całej reszty świata. Nie jest bezwzględnym wymogiem dla każdej strony, ale zwykle warto go dodać, jeśli masz wersję domyślną albo selektor języka. Jego brak utrudnia Google wybór adresu dla użytkownika bez dopasowanego języka.

Dlaczego standardowa sitemapa Astro może nie wystarczyć?

Przy częściowych tłumaczeniach albo wersjach zapasowych standardowe integracje emitują alternatywne adresy dla nieistniejących tłumaczeń i wpisują do sitemapy strony będące w rzeczywistości treścią zapasową. By nie wysyłać w ten sposób błędnego sygnału Google, musimy przejść na własne pliki generujące sitemapę i hreflang, które sprawdzają Kolekcje treści Astro i emitują wpis tylko dla realnie przetłumaczonych stron.

Tłumaczyć końcówki adresów czy zostawić je niezmienne między językami?

Jeśli zmienia się tylko prefiks języka, a końcówka adresu zostaje taka sama (/en/produkt, /de/produkt), generowanie hreflang sprowadza się do podmiany fragmentu adresu, a przełącznik języka nie potrzebuje mapy odpowiedników. Tłumaczone końcówki adresów mają sens głównie dla treści mocno osadzonych w lokalnym języku, takich jak np. blog celujący w lokalne frazy.

Czy canonical ma wskazywać na język domyślny, czy na bieżącą wersję?

Na bieżącą wersję, ponieważ każda wersja językowa powinna wskazywać samą siebie jako kanoniczną. Przykładowo, polska strona na polską, a niemiecka na niemiecką i tak dalej.

Wielojęzyczność i hreflang w Astro SSG: Zasięg globalny, wdrożenie lokalne

Artykuł w skrócie

SSG jest właściwym wyborem dla globalnego sklepu internetowego — każdy język to z góry wygenerowany HTML, idealny dla CDN, SEO i indeksacji.
Hreflang to serce operacji, bez którego wysyłasz do indeksu niemal duplikaty i prosisz Google, by zgadywało relacje. I robi to, ale z marnym skutkiem.
Trzy reguły rygoru: poprawne kody lokalizacji, sensownie ustawiony x-default, canonical dla każdej wersji językowej (a nie na język domyślny).
Pułapka częściowych tłumaczeń: standardowe integracje produkują wtedy błędny wynik, czyli emitują alternatywne adresy dla nieistniejących tłumaczeń. Rozwiązaniem są własne pliki generujące sitemapę i hreflang.
Niezmienna końcówka adresu (/en/produkt, /de/produkt) to pragmatyczny wybór domyślny. Tłumaczone końcówki rezerwuj dla treści, gdzie sam adres niesie wartość SEO (np. wpis na blogu i długi ogon zapytań).

Dlaczego SSG to właściwy wybór dla globalnego sklepu

Krajobraz 2026 roku sprzyja stronom statycznym w w internacjonalizacji z bardzo konkretnych powodów:

Każdy język dostaje własny, z góry wygenerowany HTML — optymalny dla SEO i indeksacji, bez tłumaczenia po stronie klienta, które wyszukiwarki widzą gorzej.
Łatwość buforowania na CDN — statyczne pliki rozkładają się globalnie, więc użytkownik w Tokio i w Berlinie dostaje stronę z bliskiego węzła.
Zero JavaScriptu domyślnie — szybkie ładowanie na całym świecie, co dla sklepu internetowego przekłada się wprost na konwersję.
Kolekcje treści Astro (Content Collections) — typowane, walidowane zarządzanie treścią w wielu językach.

Podejście statyczne jest łatwiejsze do buforowania, szybsze w globalnym serwowaniu i bardziej niezawodne niż tłumaczenie po stronie klienta.

Konfiguracja i18n: trasy i języki

Astro ma wbudowaną obsługę tras i18n. Przykładowa konfiguracja deklaruje obsługiwane języki i język domyślny:

Code

// astro.config.mjs
import { defineConfig } from 'astro/config'
 
export default defineConfig({
  site: 'https://twojsklep.com',
  i18n: {
    locales: ['pl', 'en', 'de', 'ja'],
    defaultLocale: 'pl',
    routing: {
      // false = adresy domyślnego języka są krótsze (bez prefiksu /pl/)
      prefixDefaultLocale: false,
    },
  },
})

Decyzja prefixDefaultLocale jest istotna o tyle, że false daje czystsze adresy dla języka domyślnego (/produkt zamiast /pl/produkt), co w większości przypadków wystarcza. true wybieraj wtedy, jeśli szczególnie zależy Ci na spójności struktury (każdy język z prefiksem).

Trasy oparte na prefiksie (/en/, /de/) są prostsze i działają ze statycznym hostingiem. Subdomeny (en.sklep.com) bywają lepsze pod SEO (ale nie zawsze i nie należy ich robić na siłę), ale wymagają konfiguracji DNS i serwera — dla SSG prefiks jest pragmatycznym standardem.

Astro pozwala też zdefiniować języki zapasowe dla poszczególnych języków, by użytkownik zawsze trafił na istniejącą treść, nawet jeśli dana podstrona nie ma jeszcze tłumaczenia.

Organizacja treści wielojęzycznej

Dla sklepu internetowego sprawdza się trzymanie treści w folderach dla każdego języka wewnątrz Kolekcji treści Astro (Content Collections):

Code

src/content/
├── produkty/
│   ├── pl/      # opisy po polsku
│   ├── en/      # opisy po angielsku
│   ├── de/      # opisy po niemiecku
│   └── ja/      # opisy po japońsku

Słowniki interfejsu (etykiety przycisków, komunikaty) trzymaj osobno, np. w src/i18n/*.json, i sięgaj po nie funkcją pomocniczą t('button.dodaj_do_koszyka') w oparciu o Astro.currentLocale.

Hreflang — najważniejszy sygnał SEO międzynarodowego

To jest serce całej operacji. mówi Google, które URL-e są swoimi tłumaczeniami i w jakim są języku. Bez niego wysyłasz do indeksu prawie duplikaty i następnie prosisz Google, by zgadywało relacje. I to robi, ale z marnym skutkiem.

Tagi hreflang generujesz w <head> szablonu, przechodząc po wszystkich językach. Astro daje do tego funkcję pomocniczą getAbsoluteLocaleUrl. W przykładzie poniżej zakładamy, że końcówka adresu jest taka sama w każdym języku, a zmienia się tylko prefiks języka:

Code

---
// src/layouts/BaseLayout.astro
import { getAbsoluteLocaleUrl } from 'astro:i18n';
 
const locales = ['pl', 'en', 'de', 'ja'] as const;
const defaultLocale = 'pl';
const currentLocale = Astro.currentLocale ?? defaultLocale;
 
const localePrefixPattern = new RegExp(`^/(${locales.filter((locale) => locale !== defaultLocale).join('|')})(?=/|$)`);
const routePath = Astro.url.pathname
  .replace(localePrefixPattern, '')
  .replace(/^\/|\/$/g, '');
 
const canonical = getAbsoluteLocaleUrl(currentLocale, routePath);
---
<head>
  <!-- Wersje językowe tej samej strony -->
  {locales.map((locale) => (
    <link
      rel="alternate"
      hreflang={locale}
      href={getAbsoluteLocaleUrl(locale, routePath)}
    />
  ))}
 
  <!-- Wersja domyślna dla nieobsłużonych języków -->
  <link
    rel="alternate"
    hreflang="x-default"
    href={getAbsoluteLocaleUrl(defaultLocale, routePath)}
  />
 
  <!-- Kanoniczny URL bieżącej wersji -->
  <link rel="canonical" href={canonical} />
</head>

Jeśli tłumaczysz końcówki adresów (/produkt/, /en/product/, /de/produkt-de/), nie podmieniaj prefiksu mechanicznie. Wtedy potrzebujesz mapy odpowiedników dla każdego języka i generujesz hreflang z tej mapy, tylko dla realnie istniejących wersji.

Trzy reguły, których pilnuj rygorystycznie:

Kody lokalizacji poprawne. Używaj en, de, zh-cn — a nie wymyślonych wariantów. Niespójne kody psują cały mechanizm.
x-default jako świadoma wersja zapasowa. Wskazuje stronę dla użytkowników, których języka nie obsługujesz; zwykle będzie to język domyślny albo selektor języka.
Canonical dla każdej wersji językowej. Każda wersja wskazuje na siebie jako kanoniczną, nie na język domyślny.

Pułapka, o której mało kto mówi: częściowe tłumaczenia

Teraz uwaga na haczyk, który wywraca standardowe konfiguracje. Dopóki każda strona istnieje w każdym języku i struktura adresów jest jednolita, standardowe integracje (@astrojs/sitemap, @astrojs/rss plus szablon emitujący hreflang) wystarczą.

Problem pojawia się, gdy masz częściowe tłumaczenia, wyświetlasz treść zapasową (interfejs po hiszpańsku, ale konkretny produkt tylko po angielsku) albo masz rozdzielone języki interfejsu i treści. Wtedy standardowe integracje zaczynają produkować błędny wynik, czyli emitują alternatywne adresy dla nieistniejących tłumaczeń i wpisują do sitemapy strony, które tak naprawdę są treścią zapasową.

Standardowy hreflang wystarczy, dopóki każda strona istnieje w każdym języku. W realnym sklepie internetowym, gdzie 30% katalogu czeka na tłumacza, ten warunek nie jest spełniony niemal nigdy.

Rozwiązanie dla dojrzałego, wielojęzycznego sklepu: własne pliki generujące sitemapę i hreflang, które przechodzą po faktycznych Kolekcjach treści Astro, sprawdzają, czy dane tłumaczenie naprawdę istnieje, i emitują wpis tylko dla realnie przetłumaczonych stron. To więcej pracy, ale to różnica między poprawnym a wprowadzającym w błąd sygnałem dla Google.

Tłumaczyć końcówki adresów czy nie?

Teraz wchodzimy w decyzję architektoniczną, która ma konsekwencje zarówno operacyjne, jak i SEO. Jeśli prefiks języka się zmienia, a końcówka adresu nie (/en/produkt, /de/produkt), generowanie hreflang sprowadza się do podmiany fragmentu adresu, przełącznik języka nie potrzebuje mapy odpowiedników, a adresy URL pozostają „kopiowalne”. Dla anglojęzycznego sklepu z tłumaczonym pokryciem to zwykle właściwy wybór.

Warto zaznaczyć natomiast, że dla treści mocno osadzonej w danym języku (np. blog kulinarny celujący w lokalną publiczność) tłumaczone końcówki adresów są warte kosztu operacyjnego, ponieważ same w sobie niosą wartość SEO. To decyzja dla konkretnego projektu i musisz wyważyć koszt utrzymania wobec zysku z lokalnych fraz w adresie.

Sitemap i dane strukturalne

Domknij obraz za pomocą dwóch elementów. Pierwszym jest sitemapa, którą konfigurujesz przez @astrojs/sitemap z opcją i18n, by automatycznie generowała wpisy dla każdego języka. Drugim są dane strukturalne (schema.org), w których wstaw inLanguage zgodne z Astro.currentLocale (to dodatkowy, jednoznaczny sygnał języka dla wyszukiwarki):

Code

---
const articleSchema = {
  '@context': 'https://schema.org',
  '@type': 'Product',
  inLanguage: Astro.currentLocale ?? 'pl',
  // pozostałe pola produktu
};
---
<script type="application/ld+json" set:html={JSON.stringify(articleSchema)} />

Werdykt Labu

Globalny zasięg sklepu internetowego zaczyna się od poprawnej warstwy technicznej, a Astro SSG daje dobry fundament — z góry wygenerowany HTML dla każdego języka, dobrze działający z CDN i SEO. Kluczowe są jednak szczegóły: poprawne kody, świadomie ustawiony x-default i canonical dla każdej wersji językowej. Standardowe integracje wystarczą przy pełnym, jednolitym tłumaczeniu, ale już dla częściowych tłumaczeń i wersji zapasowych musisz przejść na własne pliki generujące sitemapę i hreflang, które emitują tylko realnie istniejące wersje. To różnica między poprawną indeksacją a zalaniem Google duplikatami. Pamiętaj, źle skonfigurowany hreflang mocno wpływa na jakość Twojej strony i może przepalić część budżetu włożonego w tłumaczenia oraz wejście na rynek.

Audyt techniczny i optymalizacja pod kątem SEO i GEO.

SEO & Performance

Artykuł w skrócie

SSG jest właściwym wyborem dla globalnego sklepu internetowego — każdy język to z góry wygenerowany HTML, idealny dla CDN, SEO i indeksacji.
Hreflang to serce operacji, bez którego wysyłasz do indeksu niemal duplikaty i prosisz Google, by zgadywało relacje. I robi to, ale z marnym skutkiem.
Trzy reguły rygoru: poprawne kody lokalizacji, sensownie ustawiony x-default, canonical dla każdej wersji językowej (a nie na język domyślny).
Pułapka częściowych tłumaczeń: standardowe integracje produkują wtedy błędny wynik, czyli emitują alternatywne adresy dla nieistniejących tłumaczeń. Rozwiązaniem są własne pliki generujące sitemapę i hreflang.
Niezmienna końcówka adresu (/en/produkt, /de/produkt) to pragmatyczny wybór domyślny. Tłumaczone końcówki rezerwuj dla treści, gdzie sam adres niesie wartość SEO (np. wpis na blogu i długi ogon zapytań).

Dlaczego SSG to właściwy wybór dla globalnego sklepu

Krajobraz 2026 roku sprzyja stronom statycznym w w internacjonalizacji z bardzo konkretnych powodów:

Każdy język dostaje własny, z góry wygenerowany HTML — optymalny dla SEO i indeksacji, bez tłumaczenia po stronie klienta, które wyszukiwarki widzą gorzej.
Łatwość buforowania na CDN — statyczne pliki rozkładają się globalnie, więc użytkownik w Tokio i w Berlinie dostaje stronę z bliskiego węzła.
Zero JavaScriptu domyślnie — szybkie ładowanie na całym świecie, co dla sklepu internetowego przekłada się wprost na konwersję.
Kolekcje treści Astro (Content Collections) — typowane, walidowane zarządzanie treścią w wielu językach.

Podejście statyczne jest łatwiejsze do buforowania, szybsze w globalnym serwowaniu i bardziej niezawodne niż tłumaczenie po stronie klienta.

Konfiguracja i18n: trasy i języki

Astro ma wbudowaną obsługę tras i18n. Przykładowa konfiguracja deklaruje obsługiwane języki i język domyślny:

Code

// astro.config.mjs
import { defineConfig } from 'astro/config'
 
export default defineConfig({
  site: 'https://twojsklep.com',
  i18n: {
    locales: ['pl', 'en', 'de', 'ja'],
    defaultLocale: 'pl',
    routing: {
      // false = adresy domyślnego języka są krótsze (bez prefiksu /pl/)
      prefixDefaultLocale: false,
    },
  },
})

Astro pozwala też zdefiniować języki zapasowe dla poszczególnych języków, by użytkownik zawsze trafił na istniejącą treść, nawet jeśli dana podstrona nie ma jeszcze tłumaczenia.

Organizacja treści wielojęzycznej

Dla sklepu internetowego sprawdza się trzymanie treści w folderach dla każdego języka wewnątrz Kolekcji treści Astro (Content Collections):

Code

src/content/
├── produkty/
│   ├── pl/      # opisy po polsku
│   ├── en/      # opisy po angielsku
│   ├── de/      # opisy po niemiecku
│   └── ja/      # opisy po japońsku

Hreflang — najważniejszy sygnał SEO międzynarodowego

Code

---
// src/layouts/BaseLayout.astro
import { getAbsoluteLocaleUrl } from 'astro:i18n';
 
const locales = ['pl', 'en', 'de', 'ja'] as const;
const defaultLocale = 'pl';
const currentLocale = Astro.currentLocale ?? defaultLocale;
 
const localePrefixPattern = new RegExp(`^/(${locales.filter((locale) => locale !== defaultLocale).join('|')})(?=/|$)`);
const routePath = Astro.url.pathname
  .replace(localePrefixPattern, '')
  .replace(/^\/|\/$/g, '');
 
const canonical = getAbsoluteLocaleUrl(currentLocale, routePath);
---
<head>
  <!-- Wersje językowe tej samej strony -->
  {locales.map((locale) => (
    <link
      rel="alternate"
      hreflang={locale}
      href={getAbsoluteLocaleUrl(locale, routePath)}
    />
  ))}
 
  <!-- Wersja domyślna dla nieobsłużonych języków -->
  <link
    rel="alternate"
    hreflang="x-default"
    href={getAbsoluteLocaleUrl(defaultLocale, routePath)}
  />
 
  <!-- Kanoniczny URL bieżącej wersji -->
  <link rel="canonical" href={canonical} />
</head>

Trzy reguły, których pilnuj rygorystycznie:

Kody lokalizacji poprawne. Używaj en, de, zh-cn — a nie wymyślonych wariantów. Niespójne kody psują cały mechanizm.
x-default jako świadoma wersja zapasowa. Wskazuje stronę dla użytkowników, których języka nie obsługujesz; zwykle będzie to język domyślny albo selektor języka.
Canonical dla każdej wersji językowej. Każda wersja wskazuje na siebie jako kanoniczną, nie na język domyślny.

Pułapka, o której mało kto mówi: częściowe tłumaczenia

Standardowy hreflang wystarczy, dopóki każda strona istnieje w każdym języku. W realnym sklepie internetowym, gdzie 30% katalogu czeka na tłumacza, ten warunek nie jest spełniony niemal nigdy.

Tłumaczyć końcówki adresów czy nie?

Sitemap i dane strukturalne

Code

---
const articleSchema = {
  '@context': 'https://schema.org',
  '@type': 'Product',
  inLanguage: Astro.currentLocale ?? 'pl',
  // pozostałe pola produktu
};
---
<script type="application/ld+json" set:html={JSON.stringify(articleSchema)} />

Werdykt Labu

Audyt techniczny i optymalizacja pod kątem SEO i GEO.

SEO & Performance

Wielojęzyczność i hreflang w Astro SSG: Zasięg globalny, wdrożenie lokalne

Dlaczego SSG to właściwy wybór dla globalnego sklepu

Konfiguracja i18n: trasy i języki

Organizacja treści wielojęzycznej

Hreflang — najważniejszy sygnał SEO międzynarodowego

Pułapka, o której mało kto mówi: częściowe tłumaczenia

Tłumaczyć końcówki adresów czy nie?

Sitemap i dane strukturalne

Czytaj dalej

Wielojęzyczność i hreflang w Astro SSG: Zasięg globalny, wdrożenie lokalne

Dlaczego SSG to właściwy wybór dla globalnego sklepu

Konfiguracja i18n: trasy i języki

Organizacja treści wielojęzycznej

Hreflang — najważniejszy sygnał SEO międzynarodowego

Pułapka, o której mało kto mówi: częściowe tłumaczenia

Tłumaczyć końcówki adresów czy nie?

Sitemap i dane strukturalne

Czytaj dalej