Astro

A dedicated @localess/astro package is on the roadmap. Until it ships, integrate Astro with Localess by fetching content with the framework-agnostic JavaScript client and (optionally) injecting the Visual Editor sync script.

A dedicated @localess/astro package is on the roadmap. Until it ships, integrate Astro with Localess by fetching content with the framework-agnostic JavaScript client and (optionally) injecting the Visual Editor sync script.

1. Fetch content

Use @localess/client inside an Astro page or component frontmatter — code there runs at build/server time, so your API token stays out of the browser bundle.

---
// src/pages/[locale]/index.astro
import { localessClient } from "@localess/client";

const client = localessClient({
  origin: import.meta.env.LOCALESS_ORIGIN,
  spaceId: import.meta.env.LOCALESS_SPACE_ID,
  token: import.meta.env.LOCALESS_TOKEN,
});

const { locale } = Astro.params;
const content = await client.getContentBySlug("home", { locale });
const ui = await client.getTranslations(locale ?? "en");
---

<main>
  <h1>{content.data?.title}</h1>
  <button>{ui["common.submit"]}</button>
</main>

Generate TypeScript types with the CLI for full type safety.

2. Enable the Visual Editor (optional)

Astro's static-first model means live editing typically runs only in development or on dynamically rendered pages.

Option A — Programmatic injection

Use loadLocalessSync from @localess/client in a client-side script block:

---
const origin = import.meta.env.LOCALESS_ORIGIN;
---
<script define:vars={{ origin }}>
  import { loadLocalessSync } from "@localess/client";
  loadLocalessSync(origin);
</script>

Option B — Manual script tag

Add the sync script directly to a layout's <head>:

---
const origin = import.meta.env.LOCALESS_ORIGIN;
---
<head>
  <script
    id="localess-js-sync"
    type="text/javascript"
    async
    src={`${origin}/scripts/sync-v1.js`}
  ></script>
</head>

Subscribing to edit events

For pages that need live updates, subscribe to window.localess events in a client script:

<script>
  if (window.localess) {
    window.localess.on(["input", "change"], (event) => {
      // Re-render via your hydration framework of choice
      console.log(event.data);
    });
  }
</script>

Marking editable elements

Use localessEditable and localessEditableField from @localess/client to mark elements for Visual Editor selection:

---
import { localessEditable, localessEditableField } from "@localess/client";
---

<section {...localessEditable(data)}>
  <h1 {...localessEditableField("title")}>{data.title}</h1>
</section>

See Visual Editor for the full event list and attribute reference.

Roadmap

@localess/astro will ship integrations for Astro's content collection model and an island component analogous to @localess/react's LocalessComponent. Track progress on GitHub.