search

CodeStitchOfficial / Advanced-Astro-v4-i18n

This Astro advanced kit includes a pre-configured multi-language setup, along with five pages filled with CodeStitch components. Everything is ready to go right from the start, complete with an i18n integration, LESS preprocessing and a blog powered by Astro’s content collections.
https://advanced-astro-kit-i18n.netlify.app/
Creative Commons Zero v1.0 Universal
19 stars 5 forks source link
astrojs i18n starter-kit

readme

Advanced Astro v4 - i18n

This Astro advanced kit includes a pre-configured multi-language setup, along with five pages filled with CodeStitch components. Everything is ready to go right from the start, offering a fantastic introduction to the advantages of a Static Site Generator, complete with LESS preprocessing and a blog powered by Astro’s content collections.

View Live Result

Table of Contents

Overview

This Advanced kit includes a pre-configured Astro environment, which allows for repeated components, centralized data and greater room to scale as your clients grow. The kit runs the latest major Astro version, v4. On top of this, internationalization has been provided througha the Astrolicious i18n integration to create a multilingual website, scalable to as many languages as necessary. The blog is powered by Astro's Content Collections. This can easily be adapted to anything which requires changing content, such as menus, job listing boards, portfolios and much more. It could even be extended by a CMS to allow your clients to manage their content on their own.

An example website has also been provided, with easy substitution of website sections possible through the use of CodeStitch's vanilla component library. This kit aims to get any project off the ground in as little time as possible, with deployment being possible in as little as two minutes.

Getting Started

  1. At the top right of the GitHub Repository, click the green Use this template button, then click Create a new repository.
  2. Follow the instructions to create a new repository, using this repo as a template.
  3. When created, clone the repository to your local machine.
  4. Run npm install to install all dependencies.
  5. Run npm run dev to start the project and spin up a development server on localhost:4321.

Running npm run dev will start a development server and begin LESS preprocessing.

Next, it is recommended to update data/client.json with some new information about this project. Through the power of templating, the project's <head> and contact information will automatically be filled out, providing a first peek into some of the benefits of SSGs.

You can find all of CodeStitches :root variables, as well as .cs-topper, .cs-title and .cs-text, within the root stylesheet. Feel free to adjust these, or use our Content Flair micro-stitches, to update site-wide styles quickly.

Commands

All commands are run from the root of the project, from a terminal:

Command Action
npm install Installs dependencies
npm run dev Starts local dev server at localhost:4321
npm run build Build your production site to ./dist/
npm run preview Preview your build locally, before deploying
npm run astro ... Run CLI commands like astro add, astro check
npm run astro -- --help Get help using the Astro CLI

Prerequisites

Only the vanilla web technologies are required before using this kit, with familiarity with Astro and React-style Components and props are recommended. A lot of the leg-work for the non-vanilla technologies has been done for you. If you would like to read up on some of these things, we recommend the following resources:

  1. Astro's Documentation
  2. Astro Crash Course in 20 Minutes!
  3. i18next Crash Course

Features

This kit ships the following packages:

Project Structure

Astro leverages an opinionated folder layout for your project. Every Astro project root should include the following directories and files:

Project Tree

.
├── public/
|   |—— assets/
|   |   |—— favicons/
|   |   |—— fonts/
|   |   |—— images/
|   |   |—— js/
|   |   └── svgs/
|   |—— _redirects
|   |—— robots.txt
|   └── sitemap.html
├── src/
|   ├── assets/
|   |   └── images/
|   ├── components/
│   │   └── TemplateComponents 
│   ├── content/ /
│   │   ├── blog/ 
│   │   └── config.ts 
│   ├── data/
│   │   ├── client.json 
│   │   └── navData.json 
│   ├── icons/ 
│   ├── locales/ 
│   │   ├── en 
│   │   └── fr
│   ├── layouts/
│   │   └── BaseLayout.astro
│   ├── routes/ 
|   |   |── index.astro /* Accessible at / and /fr by default */
|   |   |—— about.astro /* Accessible at /about and /fr/about by default etc. */
|   |   |—— contact.astro
│   │   └── blog/
│   │   |   ├── [post].astro /* Dynamically generates individual blog pages */
│   │   |   └── index.astro /* Blog landing page */
│   │   └── projects/
│   │       ├── project-1.astro
│   │       └── project-2.astro
|   |── styles/
|   └── utils/
|       |── global.d.ts /* used by the ThemeProvider component */
|       └── utils.ts /* place any utility functions here */
├── .astro.config.mjs
├── .postcss.config.cjs
└── tsconfig.json

Source Files and Folders

Source Files and Folders

node_modules/*

Created after you run npm install. This directory contains the code for all the dependencies that power this kit. It comes as standard with any NodeJS-powered project, much like the package.json and package-lock.json files. You can safely ignore this directory in your day-to-day work.

dist/

Created after running npm build. This will hold the final build of your site.

public/*

The public/ directory is for files and assets in your project that do not need to be processed during Astro’s build process. The files in this folder will be copied into the build folder untouched, and then your site will be built.

This behavior makes public/ ideal for common assets like images and fonts, or special files such as_redirects, robots.txt and sitemap.xml.

You can place CSS and JavaScript in your public/ directory, but be aware that those files will not be bundled or optimized in your final build.

public/admin

This folder contains config/yml, which is where Decap CMS configuration options lives. More information about options in Decap docs

src/*

The src/ folder is where most of your project source code lives. This includes:

Astro processes, optimizes, and bundles your src/ files to create the final website that is shipped to the browser. Unlike the static public/ directory, your src/ files are built and handled for you by Astro.

src/assets

Contains all assets you want optimized by Astro (such as assets used in <Picture /> components for example) must be placed in src.

public/assets/images/blog is where the images uploaded on the CMS will be stored.

src/components

Components are reusable units of code for your HTML pages. These could be Astro components, or UI framework components like React or Vue. It is common to group and organize all of your project components together in this folder.

The TemplateComponents folder contains all non-CodeStitch related components such as ThemeProvider and Select etc.

src/content

The src/content/ directory is reserved to store content collections organised in folders (e.g. src/content/blog) containing .md files, and an optional config.ts collections configuration file. No other files are allowed inside this folder.

src/data

This directory contains data files that are accessible within any template throughout the project.

src/icons

SVGs used by the component must be placed in this folder.

src/layouts

Layouts are Astro components that define the UI structure shared by one or more pages. The BaseLayout.astro file acts as a giant wrapper for each individual page, where the content is injected through the <slot />component.

src/locales

Place your json files for translations in these sub-folders. See more information in the i18n section.

src/pages

Unlike a standard non-i18n Astro project, this pages folder ships empty. Use it for pages that you want handled by the i18n package. See more information in the i18n section.

src/routes

Managed by the i18n package; place your "pages" here. See more information in the i18n section. All .astro files placed in this directory will generate pages accessible from all locales.

├── routes/ 
|   |   |── index.astro /* Accessible at / and /fr by default */
|   |   |—— about.astro /* Accessible at /about and /fr/about by default */
src/styles

It is a common convention to store your CSS, Less or Sass files in a src/styles directory.

src/utils

Contains helper functions.

astro.config.mjs

An Astro configuration file. It's already set up for you, but you can extend it with integrations to use, build options, server options, and more.

package.json and package-lock.json

The project's manifest. Standard NodeJS package files, containing the dependencies needed for the project to work.

tsconfig.json

A TypeScript configuration file. Optional. Includes TypeScript configuration options for your Astro project. Some features (like npm package imports) aren’t fully supported in the editor without a tsconfig.json file.

This kit is configured to have the strictest TS config, which you can modify of course. The paths config object comes handy to create import shortcuts.

Expanding the Project

Aimed towards freelancers, this kit was made with scalability and flexibility in mind, suiting a range of websites and client needs. As such, it is your choice whether you'd rather make small tweaks to the existing site, or clear all the page content and build a site all over again. Outlined below are some best practices for when it comes to building on top of this kit:

i18n

Internationalization is powered by the I18n for Astro integration plugin. This project is set up to work with two languages out of the box, English (default language) and French.

This plugin brings 5 major changes to our project structure:

  1. in astro.config.js
i18n({
    defaultLocale: "en",
    locales: ["fr", "en"],
    client: {
      data: true,
    },
  })

This allows to configure the integration. This minimal set up here configures the languages in your project. You can check the configuration documentation for more options to pass to this configuration object.

  1. The routes directory

Unlike a monolingual Astro project, the routes directory is where most of your .astro pages will live and what the integration uses to create routing. Any .astro file placed in this routes directory will be accessible from all locales. For example, index.astro will be accessible at /blog and /fr/blog by default.

alt text

The pages directory can still be used. It's useful when you want some urls to be unique, ie. not translated like API routes (eg. under pages/api) in 1 locale only (eg. /pages/fr/test won't be handled in a special way)

  1. The locales directory The locales directory will have one sub-directory for each locale in your project. This is where the translations live, in .json files. You are free to organize your translations as you with, but you must provide at least a src/locales/en/common.json for each locale. These json files are also referred to as namespaces.

These json files must have the same name and the same organisation of key/values pairs. The only difference will obviously be the translated content.

The default (and mandatory) name space is common.json. In this kit, we also use extra name spaces so that common.json doesn't become too bloated. You can use common.json for translations of repeated components, and other name spaces for individual pages for example.

For example: /locales/en/common.json

{
  "home": "Home",
  "about": "About",
  "projects": "Projects",
  "project-1": "Project 1",
  "project-2": "Project 2",
}

/locales/fr/common.json

{
  "home": "Accueil",
  "about": "A propos",
  "projects": "Projets",
  "project-1": "Projet 1",
  "project-2": "Projet 2",
}
  1. Accessing the namespaces' data and translating with the t() function.

Under the hood, i18next is used to manage translations. We enforce the following conventions:

To access data from a name space in an .astro file, we use the t function. Don't forget to import it first in your astro file with import { t } from "i18n:astro";.

  1. First, we create the json data.

src/locales/fr/common.json

"ctaComponent": {
    "title1": "Confiez votre projet",
    "title2": "à nos experts",
    "message": "Dites quelque chose d'accrocheur, d'informatif et d'encourageant à cliquer sur le bouton pour aller à la page de contact. J'aime ajouter cette bannière en bas de chaque page.",
    "cta":"Obtenir un devis"
},
  1. Then, in our .astro file, we import the t function and use it in JSX:

src/components/CTA.astro

---
import { t, getLocalePath } from "i18n:astro";
---
<div class="container">
  <h2 class="title">
    {t("ctaComponent.title1")}
    <br />
    {t("ctaComponent.title2")}
  </h2>
  <p>
    {t("ctaComponent.message")}
  </p>
  <a href={getLocalePath("/contact")} class="cs-button-solid">{t("ctaComponent.cta")}</a>
</div>

To access data from a name space other than common.json, the syntax will be slightly different: we must prefix with the name of the name space.

home.json

"layout": {
    "title": "Pixel Perfect Websites",
    "description": "Meta description for the page"
},

Use {t("home:layout.title")} to access the title key from the layout object in the home namespace (=.json file)

home.json

"services": [
    {
        "heading": "Service 1",
        "p": "Talk about the service with keywords people will be searching for it by. Keep it 1-2 sentences."
    },
    {
        "heading": "Service 2",
        "p": "Talk about the service with keywords people will be searching for it by. Keep it 1-2 sentences."
    },
    {
        "heading": "Service 3",
        "p": "Talk about the service with keywords people will be searching for it by. Keep it 1-2 sentences."
    }
],

To access data nested in arrays with the t function, you can use this syntax: <h2>{t("home:services.0.heading")}</h2>, where

The t function is re-exported from i18next and benefits from type-safety automatically. Have a look at i18next docs to learn more.

  1. getLocalePath Create hrefs using getLocalePath to allow you get the right url for the current locale.
---
import { getLocalePath } from "i18n:astro"
---
// This link will take you to "/contact" or "/fr/contact" depending on the current locale
<a href={getLocalePath("/contact")} class="cs-button-solid">Dynamic link</a>

Custompicturecomponent

Astro provides two built-in components that you can use to display and optimize your images.

If you want to replicate the <picture> elements with multiple srcset found in many Stitches, you can use our custom <CSPicture /> component located in /src/Components/TemplateComponents.

It uses Astro's getImage() function to create a custom image component that displays different source images based on media queries.

Note: the component will automatically convert your .jpg files to .webp! 


---
// Import the component and all the images you want to use with it
import CSPicture from "@components/TemplateComponents/CSPicture.astro";
import mobileImage from "@assets/images/construction-m.jpg"
import desktopImage from "@assets/images/cabinets2.jpg"
import fallbackImage from "@assets/images/cabinets2.jpg"
---

  <CSPicture
    mobileImgUrl={mobileImage}
    mobileMediaWidth="600px"
    desktopImgUrl={desktopImage}
    desktopMediaWidth="601px"
    fallbackImgUrl={fallbackImage}
    alt=""
  />

It is currently set up to

  1. accept 3 images (mobile, desktop and fallback) that can be not only different sizes, crops but also completely different assets, as demnnstrated here.
  2. accept mobile and desktop media width if you want to adjust these sizes on a case by case basis.

You can of course adjust the sizes of attributes baased on your customization's needs directly in the component.

Astro content collections

In /src/content, you will see a config.ts file. This is where you can configure Astro Content Collections. This step is not necessary, but it will supercharge your Astro pages and content. Collections help to

This template already has Content Collections configured for immediate use of the blog content, but you could use them to power up the Portfolio or Gallery for example.

Preloading images

THis kit takes advantage of the preload attribute to fetch images above the fold with higher priority, resulting in improved performances and reducing flashes of unstyled content. Preloaded images are used on the index page for the hero image as well as on all other pages in the Landing component.

You will notice this snippet at the top of every .astro page:

---
// Optimize our landing image and pass it as props to the BaseLayout (for preloading) and Landing (for rendering)
import {getOptimizedImage} from "../js/utils"
import landingImage from "../assets/images/landing.jpg" // <-- THE PATH TO THE ASSET YOU WANT TO PRELOAD - The asset must live in src
const optimizedImage = await getOptimizedImage(landingImage)
---

You only need to change the path of the asset you want to preload. The rest is managed behind the scenes.

Deployment

  1. Before you deploy, it is recommended to test the build. Run npm run build to build the project. Once done, run npm run preview which you can access on http://localhost:4321/. This allows you to test your website as if it was deployed on your host.
  2. Ensure the sitemap, robots.txt and _redirects have been filled out. Instructions and tools for how to do so can be found in the File Structure section
  3. Netlify is the recommended hosting provider. If you choose another one, make sure to modify the _redirects code to handle the 404 page. Navigate to your Netlify Admin Panel, click Add new site | Import an existing project
  4. Follow the instructions to connect your GitHub repository to Netlify.
  5. Once deployed, go to the project's page, click on Site configuration then Identity in the navigation, then click Enable Identity
  6. Invite yourself, and the client, to the site
  7. While in the Identity tab, click the "Settings and usage" button to open the settings options. Then, do the following:
    • Go to Registration / Registration Preferences, and set registration from Public to Invite Only
    • Go to Registration / External Providers and add a provider. We recommend Google, so the client can login with Google in 1 click.
    • Go to Services / Git Gateway and enable it.

Acknowledgments

The author would like to acknowledge:

Conclusion

I hope that this kit will prove useful to you. If you have any questions or would like to connect, feel free to reach out on Twitter or at buckybuck on Discord.

Happy coding! Geoffrey