npm package: @inlang/paraglide-astro
Description: A fully type-safe i18n library specifically designed for partial hydration patterns like Astro's islands.
Author: inlang
Latest version: 0.4.1
Deprecated: use the paraglide-js package directly with v2 or above https://www.npmjs.com/package/@inlang/paraglide-js. the astro adapter is not needed anymore

---
imports: 
  - https://cdn.jsdelivr.net/npm/@opral/markdown-wc-doc-elements/dist/doc-callout.js
---

<doc-callout type="warning">
  Paraglide JS 2.0 does not need the Astro adapter anymore. Please use the [Paraglide JS 2.0 Astro](https://inlang.com/m/gerre34r/library-inlang-paraglideJs/astro) documentation instead.
</doc-callout>

Paraglide JS 2.0 does not need the Astro adapter anymore. Please use the [Paraglide JS 2.0 Astro](https://inlang.com/m/gerre34r/library-inlang-paraglideJs/astro) documentation instead.

![Dead Simple i18n. Typesafe, Small Footprint, SEO-Friendly and with an IDE Integration.](https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-astro/assets/og.png)

<doc-features>
<doc-feature text-color="#0F172A" color="#E1EFF7" title="Uses astro:i18n for routing" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-astro/assets/use-astro-i18n.png"></doc-feature>
<doc-feature text-color="#0F172A" color="#E1EFF7" title="Tiny Bundle Size" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-astro/assets/bundle-size.png"></doc-feature>
<doc-feature text-color="#0F172A" color="#E1EFF7" title="Only ships messages used on islands" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-astro/assets/islands-only.png"></doc-feature>
</doc-features>

[![Inlang-ecosystem compatibility badge](https://cdn.jsdelivr.net/gh/opral/monorepo@main/inlang/assets/md-badges/inlang.svg)](https://inlang.com)

# Gettting Started 

```bash
npx @inlang/paraglide-js init
npm i @inlang/paraglide-astro
```

This will generate `messages/{lang}.json` files for each of your languages. That's where your translations live.

Register the Integration in `astro.config.mjs`:

```js
import paraglide from "@inlang/paraglide-astro"

export default {
	// Use astro's i18n routing for deciding which language to use
	i18n: {
		locales: ["en", { code: "de", path: "deutsch" }],
		defaultLocale: "en",
	},

	integrations: [
		paraglide({
			// recommended settings
			project: "./project.inlang",
			outdir: "./src/paraglide", //where your files should be
		}),
	],
}
```

## Switching the language 

To switch the language, route to the language of interest. For example, to switch to German, route to `/de/page`.

> The `setLanguageTag` function does not do anything in the Astro adapter. See https://github.com/opral/inlang-paraglide-js/issues/187

## Passing the Language to the Client

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 { languageTag } from "../paraglide/runtime";
---

<!doctype html>
<html lang={languageTag()} dir={Astro.locals.paraglide.dir}>
    <slot />
</html>
```

# Usage

## Adding & using messages

Messages live in `messages/{lang}.json` files. Add a message to get started

```json
// messages.en.json
{
	"hello": "Hello {name}!"
}
```

You can edit which languages you support in `project.inlang/settings.json`.

```json
{
	"languageTags": ["en", "de"],
	"sourceLanguageTag": "en"
}
```

Use messages in code by importing from the `paraglide/messages.js` file generated by the compiler.

```astro
---
import * as m from "../paraglide/messages.js";
---

<h1>{m.hello({ name: "Samuel" })}</h1>
```

Vite can tree-shake the messages with no extra work from you. Only messages that are used on an Island will be included in the client bundle.

## Understanding Language 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 { languageTag } from "$paraglide/runtime";
---

<!doctype html>
<html lang={languageTag()} dir={Astro.locals.paraglide.dir}>
    <slot />
</html>
---
```

You can also access the current language and text-direction via `Astro.locals.paraglide.lang` and `Astro.locals.paraglide.dir` respectively.

## 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.

# Roadmap

- Improved Server-Rendering support
- Automatic Link-Map generation

# Playground

Check out an example Astro project with Paraglide integration on [StackBlitz](https://stackblitz.com/~/github.com/LorisSigrist/paraglide-astro-example)