Skip to content

Commit

Permalink
Merge commit '1d7ab17f64d675555162f20bb0092be09788d626'
Browse files Browse the repository at this point in the history
  • Loading branch information
@samuelstroschein
samuelstroschein committed Jan 30, 2025
2 parents bbabc97 + 1d7ab17 commit fd69385
Show file tree
Hide file tree
Showing 69 changed files with 1,331 additions and 953 deletions.
115 changes: 17 additions & 98 deletions inlang/packages/paraglide/paraglide-astro/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,15 +30,12 @@ Register the Integration in `astro.config.mjs`:
import paraglideAstro from "@inlang/paraglide-astro"

export default {
// Use astro's i18n routing for deciding which language to use
i18n: {
defaultLocale: "en",
locales: ["en", "de"],
},
integrations: [
paraglideAstro({
project: "./project.inlang",
outdir: "./src/paraglide",
// define your strategy
strategy: ["pathname", "baseLocale"]
}),
],
}
Expand All @@ -65,99 +62,6 @@ setLocale("de")

Refer to the Paraglide JS docs https://inlang.com/m/gerre34r/library-inlang-paraglideJs/getting-started.

## Understanding Locale Detection

Paraglide-Astro relies on [`astro:i18n`](https://docs.astro.build/en/guides/internationalization/)'s language detection. Place your page in a folder named for the language (or the `path` of the language) & all messages will be in that language.

```filesystem
src
├── pages
│ ├── en
│ │ ├── index.astro
│ │ └── about.astro
│ └── de
│ ├── index.astro
│ └── about.astro
```

If a page isn't in a language folder, it will use the default language.

```filesystem
src
├── pages
│ ├── index.astro // default language
│ ├── about.astro // default language
│ └── de
│ ├── index.astro // de
│ └── about.astro // de
```

You can configure which languages are available, and which is the default language in `project.inlang/settings.json`.

To save bundle size the integration doesn't ship language detection code to the client. Instead, it will read the `lang` attribute on the `<html>` tag. Make sure it is set correctly.

```astro
//src/layouts/default.astro
---
import { getLocale } from "$paraglide/runtime";
---
<!doctype html>
<html lang={getLocale()}>
<slot />
</html>
---
```

## Linking between pages

Because pages in different languages often have different slugs there is no way to automatically generate links in all languages. You will need to define a custom function.

```ts
import type { AvailableLanguageTag } from "./paraglide/runtime.js"

type AbsolutePathname = `/${string}`

const pathnames : Record<AbsolutePathname,
Record<AvailableLanguageTag, AbsolutePathname>
> = {
"/about": {
en: "/about",
de: "/de/ueber-uns",
}
}

// src/linking.ts
export function localizePathname(
pathname: AbsolutePathname,
locale: AvailableLanguageTag
) {
if(pathnames[pathname]) {
return pathnames[pathname][locale]
}
return pathname
}
```

Then use this function on your links

```tsx
<a href={localizePathname("/about", languageTag())}>{m.about()}</a>
```

## Adding Alternate Links

For SEO reasons, you should add alternate links to your page's head that point to all translations of the current page. Include the _current_ page. Make sure these are full HREFs, including the protocol and origin, not just the path.

```html
<head>
<link rel="alternate" hreflang="en" href="https://acme.com/en/about" />
<link rel="alternate" hreflang="de" href="https://acme.com/de/ueber-uns" />
</head>
```

Since only you know which pages correspond to each other this can't reliably be done automatically. Add these links manually.

# Migrating to v1 (beta)

1. Remove references of `Astro.locals.paraglide` from your code in favor of `getLocale()`. If you want to include the dir in the HTML, write your own function.
Expand All @@ -174,3 +78,18 @@ Since only you know which pages correspond to each other this can't reliably be
<slot />
</html>
```

2. Remove the `astro:i18n` package. Paraglide JS 2.0 has native support for routing.

```diff
// astro.config.mjs

- i18n: {
- defaultLocale: "en",
- locales: ["en", "de"],
- },
paraglideAstro({
// ...
})

```
11 changes: 0 additions & 11 deletions inlang/packages/paraglide/paraglide-astro/example/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,2 @@
# Astro + Paraglide Example
This is an example project of how to use Paraglide with Astro. It properly switches between languages, demonstrates the fine-grained message splitting, and handles SEO properly.

Here are some interesting files to look at:
- `src/middleware` - Set's the language based on the URL
- `src/layouts/HTML.astro` - Shows how to set the `lang` attribute on the `<html>` tag
- `src/components/BaseHead.astro` - Shows how to set the `rel="alternate"` links for SEO
- `src/components/Counter.astro` - Shows how to use Paraglide on an Island
- `src/pages/index.astro` - Shows how to use Paraglide on a page. Since these are not Islands, they are not included in the JS bundle.

We encourage you to run the `build` command and inspect the output. You will notice that only the messages used on the client are shipped in the JS bundle. This is despite no manual message-splitting having been done. This is because Paraglide generates **tree-shakeable** code for your messages. That's the power of Paraglide!

This example also has `@inlang/paraglide-vite` set up, which automatically re-runs the compile on message changes. This is not required, but it makes development much easier. You can see how it's set up in `astro.config.mjs`.
18 changes: 1 addition & 17 deletions inlang/packages/paraglide/paraglide-astro/example/astro.config.mjs
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,18 @@
import paraglideAstro from "@inlang/paraglide-astro";
import { defineConfig } from "astro/config";
import sitemap from "@astrojs/sitemap";
import svelte, { vitePreprocess } from "@astrojs/svelte";
import node from "@astrojs/node";

// https://astro.build/config
export default defineConfig({
//configure this to your domain name
//site: "https://acme.com",

i18n: {
defaultLocale: "en",
locales: ["en", "de"],
},
integrations: [
sitemap({
i18n: {
defaultLocale: "en",
locales: {
en: "en-US",
de: "de-CH",
},
},
}),
svelte({
preprocess: [vitePreprocess()],
}),
paraglideAstro({
project: "./project.inlang",
outdir: "./src/paraglide",
strategy: ["pathname", "baseLocale"],
}),
],
output: "server",
Expand Down
55 changes: 27 additions & 28 deletions inlang/packages/paraglide/paraglide-astro/example/package.json
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,29 @@
{
"name": "@inlang/paraglide-astro-example",
"type": "module",
"version": "0.1.0",
"private": "true",
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "paraglide-js compile --project ./project.inlang && astro check && astro build",
"preview": "astro preview",
"astro": "astro"
},
"dependencies": {
"@astrojs/node": "^9.0.1",
"@astrojs/sitemap": "3.2.1",
"@astrojs/svelte": "^7.0.3",
"astro": "^5.1.6",
"@astrojs/check": "^0.9.4",
"typescript": "^5.5.2",
"svelte": "^5.17.5"
},
"files": [
"*",
".gitignore"
],
"devDependencies": {
"@inlang/paraglide-astro": "workspace:*",
"@inlang/paraglide-js": "workspace:*"
}
"name": "@inlang/paraglide-astro-example",
"type": "module",
"version": "0.1.0",
"private": "true",
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "paraglide-js compile --project ./project.inlang && astro check && astro build",
"preview": "astro preview",
"astro": "astro"
},
"dependencies": {
"@astrojs/node": "^9.0.1",
"@astrojs/svelte": "^7.0.3",
"astro": "^5.1.6",
"@astrojs/check": "^0.9.4",
"typescript": "^5.5.2",
"svelte": "^5.17.5"
},
"files": [
"*",
".gitignore"
],
"devDependencies": {
"@inlang/paraglide-astro": "workspace:*",
"@inlang/paraglide-js": "workspace:*"
}
}
44 changes: 29 additions & 15 deletions inlang/packages/paraglide/paraglide-astro/example/src/components/BaseHead.astro
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,16 @@
---
import '../styles/global.css';
import { locales, isLocale } from '../paraglide/runtime.js';
import { getAbsoluteLocaleUrl } from 'astro:i18n';
import "../styles/global.css";
import { locales, deLocalizePath, localizePath } from "../paraglide/runtime.js";
interface Props {
title: string;
description: string;
image?: string;
}
const { title, description, image = '/blog-placeholder-1.jpg' } = Astro.props;
const { title, description, image = "/blog-placeholder-1.jpg" } = Astro.props;
function removeLocaleFromPath(path: string) {
const [maybeLanguage, ...rest] = path.split('/').filter(Boolean);
return isLocale(maybeLanguage) ? rest.join('/') : path;
}
const pathWithoutLocale = removeLocaleFromPath(Astro.url.pathname);
const pathWithoutLocale = deLocalizePath(Astro.url.pathname);
---

<!-- Global Metadata -->
Expand All @@ -26,15 +20,35 @@ const pathWithoutLocale = removeLocaleFromPath(Astro.url.pathname);
<meta name="generator" content={Astro.generator} />

<!-- Font preloads -->
<link rel="preload" href="/fonts/atkinson-regular.woff" as="font" type="font/woff" crossorigin />
<link rel="preload" href="/fonts/atkinson-bold.woff" as="font" type="font/woff" crossorigin />
<link
rel="preload"
href="/fonts/atkinson-regular.woff"
as="font"
type="font/woff"
crossorigin
/>
<link
rel="preload"
href="/fonts/atkinson-bold.woff"
as="font"
type="font/woff"
crossorigin
/>

<!-- Primary Meta Tags -->
<title>{title}</title>
<meta name="title" content={title} />
<meta name="description" content={description} />

<!-- Alternate Locale Versions -->
{locales.map(lang => (
<link rel="alternate" hreflang={lang} href={getAbsoluteLocaleUrl(lang, pathWithoutLocale)} />
))}
{
locales.map((locale) => (
<link
rel="alternate"
hreflang={locale}
href={localizePath(pathWithoutLocale, {
locale: locale,
})}
/>
))
}
8 changes: 0 additions & 8 deletions inlang/packages/paraglide/paraglide-astro/src/alias.ts
View file

This file was deleted.

26 changes: 0 additions & 26 deletions inlang/packages/paraglide/paraglide-astro/src/ambient.d.ts
View file

This file was deleted.

Loading

0 comments on commit fd69385

Please sign in to comment.