Initial implementation of localization

This commit is contained in:
adilallo
2026-01-29 22:17:44 -07:00
parent 1714e7f930
commit 2f37031411
29 changed files with 813 additions and 4365 deletions
@@ -1,6 +1,7 @@
"use client";
import { memo } from "react";
import { useTranslation } from "../../contexts/MessagesContext";
import { useAnalytics } from "../../hooks";
import AskOrganizerView from "./AskOrganizer.view";
import type {
@@ -35,12 +36,15 @@ const AskOrganizerContainer = memo<AskOrganizerProps>(
title,
subtitle,
description,
buttonText = "Ask an organizer",
buttonHref = "#",
buttonText,
buttonHref,
className = "",
variant = "centered",
onContactClick,
}) => {
const t = useTranslation();
const defaultButtonText = buttonText ?? t("askOrganizer.buttonText");
const defaultButtonHref = buttonHref ?? t("askOrganizer.buttonHref");
const { trackEvent, trackCustomEvent } = useAnalytics();
const resolvedVariant: AskOrganizerVariant = variant ?? "centered";
@@ -74,8 +78,8 @@ const AskOrganizerContainer = memo<AskOrganizerProps>(
{
component: "AskOrganizer",
variant: resolvedVariant,
buttonText,
buttonHref,
buttonText: defaultButtonText,
buttonHref: defaultButtonHref,
},
onContactClick as
| ((_data: Record<string, unknown>) => void)
@@ -92,8 +96,8 @@ const AskOrganizerContainer = memo<AskOrganizerProps>(
title={title}
subtitle={subtitle}
description={description}
buttonText={buttonText}
buttonHref={buttonHref}
buttonText={defaultButtonText}
buttonHref={defaultButtonHref}
className={className}
sectionPadding={sectionPadding}
contentGap={`${contentGap} ${styles.container}`}
@@ -1,3 +1,6 @@
"use client";
import { useTranslation } from "../../contexts/MessagesContext";
import ContentLockup from "../ContentLockup";
import Button from "../Button";
import type { AskOrganizerViewProps } from "./AskOrganizer.types";
@@ -16,11 +19,14 @@ function AskOrganizerView({
labelledBy,
onContactClick,
}: AskOrganizerViewProps) {
const t = useTranslation();
const ariaLabel = t("askOrganizer.ariaLabel");
return (
<section
className={`${sectionPadding} ${className}`}
aria-labelledby={labelledBy}
aria-label={labelledBy ? undefined : "Ask an organizer"}
aria-label={labelledBy ? undefined : ariaLabel}
tabIndex={-1}
>
<div className={`flex flex-col ${contentGap}`}>
@@ -42,7 +48,7 @@ function AskOrganizerView({
variant={variant === "inverse" ? "primary" : "default"}
className="xl:!px-[var(--spacing-scale-020)] xl:!py-[var(--spacing-scale-012)] xl:!text-[24px] xl:!leading-[28px]"
onClick={onContactClick}
ariaLabel={`${buttonText} - Contact an organizer for help`}
ariaLabel={ariaLabel}
>
{buttonText}
</Button>
@@ -1,47 +1,50 @@
"use client";
import { memo, useMemo } from "react";
import { useTranslation } from "../../contexts/MessagesContext";
import FeatureGridView from "./FeatureGrid.view";
import type { FeatureGridProps, Feature } from "./FeatureGrid.types";
const FeatureGridContainer = memo<FeatureGridProps>(
({ title, subtitle, className = "" }) => {
const t = useTranslation();
const features: Feature[] = useMemo(
() => [
{
backgroundColor: "bg-[var(--color-surface-default-brand-royal)]",
labelLine1: "Decision-making",
labelLine2: "support",
labelLine1: t("featureGrid.features.decisionMaking.labelLine1"),
labelLine2: t("featureGrid.features.decisionMaking.labelLine2"),
panelContent: "/assets/Feature_Support.png",
ariaLabel: "Decision-making support tools",
ariaLabel: t("featureGrid.features.decisionMaking.ariaLabel"),
href: "#decision-making",
},
{
backgroundColor: "bg-[#D1FFE2]",
labelLine1: "Values alignment",
labelLine2: "exercises",
labelLine1: t("featureGrid.features.valuesAlignment.labelLine1"),
labelLine2: t("featureGrid.features.valuesAlignment.labelLine2"),
panelContent: "/assets/Feature_Exercises.png",
ariaLabel: "Values alignment exercises",
ariaLabel: t("featureGrid.features.valuesAlignment.ariaLabel"),
href: "#values-alignment",
},
{
backgroundColor: "bg-[#F4CAFF]",
labelLine1: "Membership",
labelLine2: "guidance",
labelLine1: t("featureGrid.features.membershipGuidance.labelLine1"),
labelLine2: t("featureGrid.features.membershipGuidance.labelLine2"),
panelContent: "/assets/Feature_Guidance.png",
ariaLabel: "Membership guidance resources",
ariaLabel: t("featureGrid.features.membershipGuidance.ariaLabel"),
href: "#membership-guidance",
},
{
backgroundColor: "bg-[#CBDDFF]",
labelLine1: "Conflict resolution",
labelLine2: "tools",
labelLine1: t("featureGrid.features.conflictResolution.labelLine1"),
labelLine2: t("featureGrid.features.conflictResolution.labelLine2"),
panelContent: "/assets/Feature_Tools.png",
ariaLabel: "Conflict resolution tools",
ariaLabel: t("featureGrid.features.conflictResolution.ariaLabel"),
href: "#conflict-resolution",
},
],
[],
[t],
);
const labelledBy = title ? "feature-grid-headline" : undefined;
@@ -1,3 +1,6 @@
"use client";
import { useTranslation } from "../../contexts/MessagesContext";
import ContentLockup from "../ContentLockup";
import MiniCard from "../MiniCard";
import type { FeatureGridViewProps } from "./FeatureGrid.types";
@@ -9,11 +12,16 @@ function FeatureGridView({
features,
labelledBy,
}: FeatureGridViewProps) {
const t = useTranslation();
const ariaLabel = t("featureGrid.ariaLabel");
const linkText = t("featureGrid.linkText");
const linkHref = t("featureGrid.linkHref");
return (
<section
className={`p-0 lg:p-[var(--spacing-scale-064)] ${className}`}
aria-labelledby={labelledBy}
aria-label={labelledBy ? undefined : "Feature tools and services"}
aria-label={labelledBy ? undefined : ariaLabel}
>
<div className="py-[var(--spacing-scale-032)] px-[var(--spacing-scale-020)] md:pt-[var(--spacing-scale-076)] md:pb-[var(--spacing-scale-048)] lg:pb-[var(--spacing-scale-076)] md:px-[var(--spacing-scale-048)] bg-[#171717] rounded-[var(--radius-measures-radius-xlarge)] focus-within:ring-2 focus-within:ring-[var(--color-surface-default-brand-royal)] focus-within:ring-offset-2">
<div className="w-full mx-auto gap-[var(--spacing-scale-048)] lg:flex lg:items-start lg:gap-[var(--spacing-scale-048)] [container-type:inline-size]">
@@ -23,8 +31,8 @@ function FeatureGridView({
title={title}
subtitle={subtitle}
variant="feature"
linkText="Learn more"
linkHref="#"
linkText={linkText}
linkHref={linkHref}
titleId={labelledBy}
/>
</div>
+26 -21
View File
@@ -1,20 +1,25 @@
"use client";
import { memo } from "react";
import { useTranslation } from "../contexts/MessagesContext";
import Link from "next/link";
import Logo from "./Logo";
import Separator from "./Separator";
import { getAssetPath, ASSETS } from "../../lib/assetUtils";
const Footer = memo(() => {
const t = useTranslation("footer");
// Schema markup for organization information
const schemaData = {
"@context": "https://schema.org",
"@type": "Organization",
name: "Media Economies Design Lab",
email: "medlab@colorado.edu",
url: "https://communityrule.com",
name: t("organization.name"),
email: t("organization.email"),
url: t("organization.url"),
sameAs: [
"https://bsky.app/profile/medlabboulder",
"https://gitlab.com/medlabboulder",
t("social.bluesky.url"),
t("social.gitlab.url"),
],
};
@@ -55,22 +60,22 @@ const Footer = memo(() => {
{/* Contact info */}
<div className="flex flex-col items-start gap-[var(--spacing-measures-spacing-016,16px)]">
<div className="text-[var(--color-content-default-primary)] font-inter text-base leading-5 font-medium tracking-[0%] lg:text-2xl lg:leading-7 lg:font-normal">
Media Economies Design Lab
{t("organization.name")}
</div>
<a
href="mailto:medlab@colorado.edu"
href={`mailto:${t("organization.email")}`}
className="text-[var(--color-content-default-primary)] font-inter text-base leading-5 font-medium tracking-[0%] lg:text-2xl lg:leading-7 lg:font-normal hover:opacity-80 active:opacity-60 focus:opacity-80 focus:outline-none focus:ring-2 focus:ring-[var(--color-content-default-primary)] focus:ring-offset-2 focus:ring-offset-[var(--color-surface-default-primary)] transition-opacity p-2 -m-2 cursor-pointer"
>
medlab@colorado.edu
{t("organization.email")}
</a>
</div>
{/* Social media links */}
<div className="flex flex-col items-start gap-[var(--spacing-measures-spacing-016,16px)]">
<a
href="#"
href={t("social.bluesky.url")}
className="flex items-center gap-[var(--spacing-measures-spacing-06,6px)] hover:opacity-80 active:opacity-60 focus:opacity-80 focus:outline-none focus:ring-2 focus:ring-[var(--color-content-default-primary)] focus:ring-offset-2 focus:ring-offset-[var(--color-surface-default-primary)] transition-opacity p-2 -m-2 cursor-pointer group"
aria-label="Follow us on Bluesky"
aria-label={t("social.bluesky.ariaLabel")}
>
<img
src={getAssetPath(ASSETS.BLUESKY_LOGO)}
@@ -80,13 +85,13 @@ const Footer = memo(() => {
className="flex-shrink-0 group-hover:scale-110 transition-transform"
/>
<div className="text-[var(--color-content-default-primary)] font-inter text-base leading-5 font-medium tracking-[0%] lg:text-2xl lg:leading-7 lg:font-normal">
medlabboulder
{t("social.bluesky.handle")}
</div>
</a>
<a
href="#"
href={t("social.gitlab.url")}
className="flex items-center gap-[var(--spacing-measures-spacing-06,6px)] hover:opacity-80 active:opacity-60 focus:opacity-80 focus:outline-none focus:ring-2 focus:ring-[var(--color-content-default-primary)] focus:ring-offset-2 focus:ring-offset-[var(--color-surface-default-primary)] transition-opacity p-2 -m-2 cursor-pointer group"
aria-label="Follow us on GitLab"
aria-label={t("social.gitlab.ariaLabel")}
>
<img
src={getAssetPath(ASSETS.GITLAB_ICON)}
@@ -96,7 +101,7 @@ const Footer = memo(() => {
className="flex-shrink-0 grayscale group-hover:scale-110 transition-transform"
/>
<div className="text-[var(--color-content-default-primary)] font-inter text-base leading-5 font-medium tracking-[0%] lg:text-2xl lg:leading-7 lg:font-normal">
medlabboulder
{t("social.gitlab.handle")}
</div>
</a>
</div>
@@ -108,19 +113,19 @@ const Footer = memo(() => {
href="#"
className="text-[var(--color-content-default-primary)] font-inter text-base leading-5 font-medium tracking-[0%] lg:text-2xl lg:leading-7 lg:font-normal hover:opacity-80 active:opacity-60 focus:opacity-80 focus:outline-none focus:ring-2 focus:ring-[var(--color-content-default-primary)] focus:ring-offset-2 focus:ring-offset-[var(--color-surface-default-primary)] transition-opacity p-2 -m-2 cursor-pointer"
>
Use cases
{t("navigation.useCases")}
</Link>
<Link
href="/learn"
className="text-[var(--color-content-default-primary)] font-inter text-base leading-5 font-medium tracking-[0%] lg:text-2xl lg:leading-7 lg:font-normal hover:opacity-80 active:opacity-60 focus:opacity-80 focus:outline-none focus:ring-2 focus:ring-[var(--color-content-default-primary)] focus:ring-offset-2 focus:ring-offset-[var(--color-surface-default-primary)] transition-opacity p-2 -m-2 cursor-pointer"
>
Learn
{t("navigation.learn")}
</Link>
<Link
href="#"
className="text-[var(--color-content-default-primary)] font-inter text-base leading-5 font-medium tracking-[0%] lg:text-2xl lg:leading-7 lg:font-normal hover:opacity-80 active:opacity-60 focus:opacity-80 focus:outline-none focus:ring-2 focus:ring-[var(--color-content-default-primary)] focus:ring-offset-2 focus:ring-offset-[var(--color-surface-default-primary)] transition-opacity p-2 -m-2 cursor-pointer"
>
About
{t("navigation.about")}
</Link>
</div>
</div>
@@ -133,25 +138,25 @@ const Footer = memo(() => {
href="#"
className="text-[var(--color-content-default-secondary)] font-inter text-sm leading-5 font-normal tracking-[0%] lg:text-base lg:leading-6 hover:opacity-80 active:opacity-60 focus:opacity-80 focus:outline-none focus:ring-2 focus:ring-[var(--color-content-default-primary)] focus:ring-offset-2 focus:ring-offset-[var(--color-surface-default-primary)] transition-opacity p-2 -m-2 cursor-pointer"
>
Privacy Policy
{t("legal.privacyPolicy")}
</Link>
<Link
href="#"
className="text-[var(--color-content-default-secondary)] font-inter text-sm leading-5 font-normal tracking-[0%] lg:text-base lg:leading-6 hover:opacity-80 active:opacity-60 focus:opacity-80 focus:outline-none focus:ring-2 focus:ring-[var(--color-content-default-primary)] focus:ring-offset-2 focus:ring-offset-[var(--color-surface-default-primary)] transition-opacity p-2 -m-2 cursor-pointer"
>
Terms of Service
{t("legal.termsOfService")}
</Link>
<Link
href="#"
className="text-[var(--color-content-default-secondary)] font-inter text-sm leading-5 font-normal tracking-[0%] lg:text-base lg:leading-6 hover:opacity-80 active:opacity-60 focus:opacity-80 focus:outline-none focus:ring-2 focus:ring-[var(--color-content-default-primary)] focus:ring-offset-2 focus:ring-offset-[var(--color-surface-default-primary)] transition-opacity p-2 -m-2 cursor-pointer"
>
Cookies Settings
{t("legal.cookiesSettings")}
</Link>
</div>
{/* Copyright */}
<div className="text-[var(--color-content-default-secondary)] font-inter text-sm leading-5 font-normal tracking-[0%] lg:text-base lg:leading-6">
© All right reserved
{t("copyright")}
</div>
</div>
</footer>
+5 -1
View File
@@ -1,6 +1,7 @@
"use client";
import { memo } from "react";
import { useTranslation } from "../contexts/MessagesContext";
import ContentLockup from "./ContentLockup";
import HeroDecor from "./HeroDecor";
import { getAssetPath } from "../../lib/assetUtils";
@@ -15,6 +16,9 @@ interface HeroBannerProps {
const HeroBanner = memo<HeroBannerProps>(
({ title, subtitle, description, ctaText, ctaHref }) => {
const t = useTranslation();
const imageAlt = t("heroBanner.imageAlt");
return (
<section className="bg-transparent px-[var(--spacing-scale-008)] sm:px-[var(--spacing-scale-010)] md:px-[var(--spacing-scale-016)] lg:px-[var(--spacing-scale-024)] xl:px-[var(--spacing-scale-048)]">
<div className="flex flex-col gap-[var(--spacing-scale-010)]">
@@ -44,7 +48,7 @@ const HeroBanner = memo<HeroBannerProps>(
<div className="w-full h-full md:flex-1 rounded-[8px] overflow-hidden relative z-10 flex items-center justify-center">
<img
src={getAssetPath("assets/HeroImage.png")}
alt="Hero illustration"
alt={imageAlt}
className="w-full h-auto"
loading="eager"
fetchPriority="high"
@@ -0,0 +1,18 @@
"use client";
import { memo } from "react";
import LanguageSwitcherView from "./LanguageSwitcher.view";
import type { LanguageSwitcherProps } from "./LanguageSwitcher.types";
const LanguageSwitcherContainer = memo<LanguageSwitcherProps>(
({ className }) => {
// Future: Add language switching logic here
// For now, this is just a UI component
return <LanguageSwitcherView className={className} />;
},
);
LanguageSwitcherContainer.displayName = "LanguageSwitcher";
export default LanguageSwitcherContainer;
@@ -0,0 +1,9 @@
export interface LanguageSwitcherProps {
className?: string;
}
export interface Language {
code: string;
name: string;
nativeName: string;
}
@@ -0,0 +1,39 @@
"use client";
import { memo } from "react";
import type { LanguageSwitcherProps, Language } from "./LanguageSwitcher.types";
const AVAILABLE_LANGUAGES: Language[] = [
{
code: "en",
name: "English",
nativeName: "English",
},
];
function LanguageSwitcherView({ className = "" }: LanguageSwitcherProps) {
return (
<div className={className}>
<label htmlFor="language-select" className="sr-only">
Select language
</label>
<select
id="language-select"
className="bg-[var(--color-surface-default-primary)] text-[var(--color-content-default-primary)] font-inter text-sm leading-5 font-normal border border-[var(--color-surface-default-secondary)] rounded-[var(--radius-measures-radius-small)] px-[var(--spacing-scale-012)] py-[var(--spacing-scale-008)] focus:outline-none focus:ring-2 focus:ring-[var(--color-surface-default-brand-royal)] focus:ring-offset-2 cursor-pointer"
aria-label="Select language"
disabled
>
{AVAILABLE_LANGUAGES.map((language) => (
<option key={language.code} value={language.code}>
{language.nativeName}
</option>
))}
</select>
<p className="text-[var(--color-content-default-secondary)] font-inter text-xs leading-4 font-normal mt-[var(--spacing-scale-008)]">
Language switching functionality coming soon
</p>
</div>
);
}
export default memo(LanguageSwitcherView);
+2
View File
@@ -0,0 +1,2 @@
export { default } from "./LanguageSwitcher.container";
export type { LanguageSwitcherProps, Language } from "./LanguageSwitcher.types";
@@ -1,3 +1,6 @@
"use client";
import { useTranslation } from "../../contexts/MessagesContext";
import SectionHeader from "../SectionHeader";
import NumberedCard from "../NumberedCard";
import Button from "../Button";
@@ -9,6 +12,8 @@ function NumberedCardsView({
cards,
schemaJson,
}: NumberedCardsViewProps) {
const t = useTranslation();
return (
<>
<script
@@ -23,7 +28,7 @@ function NumberedCardsView({
<SectionHeader
title={title}
subtitle={subtitle}
titleLg="How CommunityRule helps"
titleLg={t("numberedCards.titleLg")}
/>
</div>
@@ -45,13 +50,13 @@ function NumberedCardsView({
{/* Default button for xsm and sm breakpoints */}
<div className="block lg:hidden">
<Button variant="default" size="large">
Create CommunityRule
{t("numberedCards.buttons.createCommunityRule")}
</Button>
</div>
{/* Outlined button for lg and xlg breakpoints */}
<div className="hidden lg:block">
<Button variant="outlined" size="large">
See how it works
{t("numberedCards.buttons.seeHowItWorks")}
</Button>
</div>
</div>
+68
View File
@@ -0,0 +1,68 @@
"use client";
import { createContext, useContext, type ReactNode } from "react";
import type messages from "../../messages/en/index";
type Messages = typeof messages;
const MessagesContext = createContext<Messages | null>(null);
interface MessagesProviderProps {
messages: Messages;
children: ReactNode;
}
export function MessagesProvider({ messages, children }: MessagesProviderProps) {
return (
<MessagesContext.Provider value={messages}>
{children}
</MessagesContext.Provider>
);
}
export function useMessages(): Messages {
const messages = useContext(MessagesContext);
if (!messages) {
throw new Error("useMessages must be used within MessagesProvider");
}
return messages;
}
/**
* Get a translation value from messages using dot notation
* @param messages - The messages object
* @param key - Dot-separated key path (e.g., "heroBanner.title")
* @returns The translation string or the key if not found
*/
function getTranslationValue(messages: Messages, key: string): string {
const keys = key.split(".");
let value: any = messages;
for (const k of keys) {
if (value && typeof value === "object" && k in value) {
value = value[k as keyof typeof value];
} else {
return key; // Fallback to key if path not found
}
}
return typeof value === "string" ? value : key;
}
/**
* Custom translation hook for client components
* @param namespace - Optional namespace to scope translations (e.g., "footer")
* @returns Translation function that accepts a key and returns the translated string
*/
export function useTranslation(namespace?: string) {
const messages = useMessages();
return (key: string): string => {
if (namespace) {
// If namespace is provided, prepend it to the key
const fullKey = `${namespace}.${key}`;
return getTranslationValue(messages, fullKey);
}
return getTranslationValue(messages, key);
};
}
+16 -6
View File
@@ -2,6 +2,8 @@ import { Inter, Bricolage_Grotesque, Space_Grotesk } from "next/font/google";
import type { Metadata } from "next";
import type { ReactNode } from "react";
import dynamic from "next/dynamic";
import { MessagesProvider } from "./contexts/MessagesContext";
import messages from "../messages/en/index";
import "./globals.css";
import ConditionalHeader from "./components/ConditionalHeader";
@@ -85,7 +87,13 @@ export const metadata: Metadata = {
},
};
export default function RootLayout({ children }: { children: ReactNode }) {
export default function RootLayout({
children,
}: {
children: ReactNode;
}) {
// Load messages for the default locale (single locale setup)
return (
<html lang="en" className="font-sans">
<head>
@@ -101,11 +109,13 @@ export default function RootLayout({ children }: { children: ReactNode }) {
<body
className={`${inter.variable} ${bricolageGrotesque.variable} ${spaceGrotesk.variable}`}
>
<div className="min-h-screen flex flex-col">
<ConditionalHeader />
<main className="flex-1">{children}</main>
<Footer />
</div>
<MessagesProvider messages={messages}>
<div className="min-h-screen flex flex-col">
<ConditionalHeader />
<main className="flex-1">{children}</main>
<Footer />
</div>
</MessagesProvider>
</body>
</html>
);
+22 -18
View File
@@ -1,4 +1,6 @@
import dynamic from "next/dynamic";
import messages from "../messages/en/index";
import { getTranslation } from "../lib/i18n/getTranslation";
import HeroBanner from "./components/HeroBanner";
import AskOrganizer from "./components/AskOrganizer";
@@ -39,31 +41,34 @@ const QuoteBlock = dynamic(() => import("./components/QuoteBlock"), {
});
export default function Page() {
// Use direct message access for server components
// This maintains type safety without requiring external i18n libraries
const t = (key: string) => getTranslation(messages, key);
const heroBannerData = {
title: "Collaborate",
subtitle: "with clarity",
description:
"Help your community make important decisions in a way that reflects its unique values.",
ctaText: "Learn how CommunityRule works",
ctaHref: "#",
title: t("heroBanner.title"),
subtitle: t("heroBanner.subtitle"),
description: t("heroBanner.description"),
ctaText: t("heroBanner.ctaText"),
ctaHref: t("heroBanner.ctaHref"),
};
const numberedCardsData = {
title: "How CommunityRule works",
subtitle: "Here's a quick overview of the process, from start to finish.",
title: t("numberedCards.title"),
subtitle: t("numberedCards.subtitle"),
cards: [
{
text: "Document how your community makes decisions",
text: t("numberedCards.cards.card1.text"),
iconShape: "blob",
iconColor: "green",
},
{
text: "Build an operating manual for a successful community",
text: t("numberedCards.cards.card2.text"),
iconShape: "gear",
iconColor: "purple",
},
{
text: "Get a link to your manual for your group to review and evolve",
text: t("numberedCards.cards.card3.text"),
iconShape: "star",
iconColor: "orange",
},
@@ -71,16 +76,15 @@ export default function Page() {
};
const featureGridData = {
title: "We've got your back, every step of the way",
subtitle:
"Use our toolkit to improve, document, and evolve your organization.",
title: t("featureGrid.title"),
subtitle: t("featureGrid.subtitle"),
};
const askOrganizerData = {
title: "Still have questions?",
subtitle: "Get answers from an experienced organizer",
buttonText: "Ask an organizer",
buttonHref: "#contact",
title: t("askOrganizer.title"),
subtitle: t("askOrganizer.subtitle"),
buttonText: t("askOrganizer.buttonText"),
buttonHref: t("askOrganizer.buttonHref"),
};
return (
+11
View File
@@ -13,6 +13,7 @@ This directory contains project documentation organized by topic.
- **[container-presentation-pattern.md](./guides/container-presentation-pattern.md)** - Container/Presentation pattern guide for component architecture
- **[content-creation.md](./guides/content-creation.md)** - Guide for creating blog content
- **[i18n-translation-workflow.md](./guides/i18n-translation-workflow.md)** - Guide for working with translations and UI content management
## Quick Navigation
@@ -51,6 +52,16 @@ See **[content-creation.md](./guides/content-creation.md)** for:
- Content guidelines
- Contribution workflow
### For Translations and UI Content
See **[i18n-translation-workflow.md](./guides/i18n-translation-workflow.md)** for:
- How to update UI text content
- Translation key structure and naming conventions
- How to extract strings from components
- How to add new translation keys
- Best practices for content creators and developers
## Additional Resources
- **Vitest Documentation**: https://vitest.dev/
+257
View File
@@ -0,0 +1,257 @@
# i18n Translation Workflow Guide
This guide explains how to work with translations in the CommunityRule application. The app uses `next-intl` for managing UI text content, making it easy for content creators and contributors to update text without modifying component code.
## Overview
All UI text is stored in JSON files under `messages/en/`. Components reference these translations using keys, allowing content to be edited independently of the codebase.
## Directory Structure
```
messages/
en/
common.json # Shared UI strings (buttons, links, labels)
components/
heroBanner.json # HeroBanner component translations
numberedCards.json # NumberedCards component translations
askOrganizer.json # AskOrganizer component translations
featureGrid.json # FeatureGrid component translations
footer.json # Footer component translations
navigation.json # Navigation items
metadata.json # Page metadata (title, description)
index.ts # Exports all messages
```
## Adding New Translation Keys
### 1. Identify the Component
Determine which component needs the translation. If it's a shared string (like a button label), add it to `common.json`. Otherwise, add it to the component-specific file.
### 2. Add the Key to the JSON File
Open the appropriate JSON file and add your translation key. Use descriptive, semantic keys:
**Good:**
```json
{
"heroBanner": {
"title": "Collaborate",
"subtitle": "with clarity"
}
}
```
**Bad:**
```json
{
"text1": "Collaborate",
"text2": "with clarity"
}
```
### 3. Use Nested Objects for Organization
Group related translations together:
```json
{
"numberedCards": {
"title": "How CommunityRule works",
"buttons": {
"createCommunityRule": "Create CommunityRule",
"seeHowItWorks": "See how it works"
}
}
}
```
### 4. Update the Component
In your component, use the translation hook:
**Server Components:**
```typescript
import { getTranslations } from "next-intl/server";
export default async function MyComponent() {
const t = await getTranslations();
return <h1>{t("heroBanner.title")}</h1>;
}
```
**Client Components:**
```typescript
"use client";
import { useTranslations } from "next-intl";
export default function MyComponent() {
const t = useTranslations();
return <h1>{t("heroBanner.title")}</h1>;
}
```
**Namespace-specific (recommended for component files):**
```typescript
const t = useTranslations("heroBanner");
return <h1>{t("title")}</h1>;
```
## Translation Key Naming Conventions
1. **Use camelCase** for keys: `buttonText`, `ariaLabel`
2. **Use descriptive names**: `createCommunityRule` not `btn1`
3. **Group by component**: Each component has its own namespace
4. **Use nested objects** for related strings: `buttons.createCommunityRule`
5. **Include context in comments**: Use `_comment` fields for clarity
Example:
```json
{
"_comment": "HeroBanner component translations",
"title": "Collaborate",
"subtitle": "with clarity",
"description": "Help your community make important decisions..."
}
```
## Extracting Strings from Components
When migrating a component to use translations:
1. **Identify hardcoded strings** in the component
2. **Create translation keys** in the appropriate JSON file
3. **Replace hardcoded strings** with `t("key.path")` calls
4. **Test the component** to ensure translations load correctly
### Example Migration
**Before:**
```typescript
export default function HeroBanner() {
return (
<div>
<h1>Collaborate</h1>
<p>with clarity</p>
</div>
);
}
```
**After:**
```typescript
"use client";
import { useTranslations } from "next-intl";
export default function HeroBanner() {
const t = useTranslations("heroBanner");
return (
<div>
<h1>{t("title")}</h1>
<p>{t("subtitle")}</p>
</div>
);
}
```
## Adding New Languages (Future)
When adding support for a new language:
1. **Create a new locale directory**: `messages/es/` (for Spanish, for example)
2. **Copy the English files** as a starting point
3. **Translate all strings** in the JSON files
4. **Update `app/i18n/routing.ts`** to include the new locale
5. **Test thoroughly** to ensure all translations are present
## Testing Translations
1. **Check for missing keys**: Ensure all translation keys used in components exist in the JSON files
2. **Verify type safety**: TypeScript will catch typos in translation keys at compile time
3. **Test in browser**: Run the dev server and verify text displays correctly
4. **Check for fallbacks**: Missing translations will show the key path (e.g., `heroBanner.title`)
## Best Practices
### For Content Creators
- **Edit JSON files directly**: No need to understand React or TypeScript
- **Use descriptive comments**: Add `_comment` fields to explain context
- **Maintain consistency**: Use the same terminology across components
- **Test changes**: Run the dev server to see your changes immediately
### For Developers
- **Use TypeScript**: Translation keys are type-safe
- **Namespace when possible**: Use `useTranslations("namespace")` for better organization
- **Server components first**: Prefer server-side translations for better performance
- **Extract incrementally**: Migrate components one at a time
## Common Patterns
### Buttons and CTAs
```json
{
"buttons": {
"createCommunityRule": "Create CommunityRule",
"seeHowItWorks": "See how it works"
}
}
```
### Aria Labels
```json
{
"ariaLabels": {
"followBluesky": "Follow us on Bluesky",
"followGitlab": "Follow us on GitLab"
}
}
```
### Dynamic Content
For content that varies (like card text), use arrays or numbered keys:
```json
{
"cards": {
"card1": { "text": "First step" },
"card2": { "text": "Second step" },
"card3": { "text": "Third step" }
}
}
```
## Troubleshooting
### Translation Key Not Found
If you see a key path like `heroBanner.title` instead of the text:
1. Check the JSON file exists and has the key
2. Verify the key path matches exactly (case-sensitive)
3. Restart the dev server if you just added the key
### TypeScript Errors
If TypeScript complains about translation keys:
1. Ensure the key exists in the JSON file
2. Check for typos in the key path
3. Verify the namespace is correct if using `useTranslations("namespace")`
### Missing Translations
If text doesn't appear:
1. Check the browser console for errors
2. Verify the component is wrapped in `NextIntlClientProvider` (for client components)
3. Ensure `getMessages()` is called in server components
## Resources
- [next-intl Documentation](https://next-intl.dev/docs)
- [Next.js Internationalization](https://nextjs.org/docs/app/guides/internationalization)
- Component-specific translation files in `messages/en/components/`
---
**Last Updated**: January 2025
**Maintained by**: CommunityRule Development Team
+59
View File
@@ -0,0 +1,59 @@
import type messages from "../../messages/en/index";
type Messages = typeof messages;
/**
* Helper function to access nested translation keys from messages object
* This provides a type-safe way to access translations in server components
* without requiring the next-intl plugin configuration.
*
* @param messages - The messages object from messages/en/index
* @param key - Dot-separated key path (e.g., "heroBanner.title")
* @returns The translation string or the key if not found
*/
export function getTranslation(
messages: Messages,
key: string,
): string {
const keys = key.split(".");
let value: any = messages;
for (const k of keys) {
if (value && typeof value === "object" && k in value) {
value = value[k as keyof typeof value];
} else {
// Fallback to key if path not found
return key;
}
}
return typeof value === "string" ? value : key;
}
/**
* Type-safe helper to get nested values from messages
* Usage: getNested(messages, "heroBanner", "title")
*/
export function getNested<T extends keyof Messages>(
messages: Messages,
namespace: T,
key: string,
): string {
const namespaceObj = messages[namespace];
if (!namespaceObj || typeof namespaceObj !== "object") {
return key;
}
const keys = key.split(".");
let value: any = namespaceObj;
for (const k of keys) {
if (value && typeof value === "object" && k in value) {
value = value[k];
} else {
return key;
}
}
return typeof value === "string" ? value : key;
}
+21
View File
@@ -0,0 +1,21 @@
/**
* Type definitions for translation keys
*
* These types provide type safety when accessing translation keys.
* The actual types are inferred from the JSON files in messages/en/
*/
// Import the message structure to ensure type safety
import type messages from "../../messages/en/index";
export type Messages = typeof messages;
// Helper type for nested key paths
export type NestedKeyOf<ObjectType extends object> = {
[Key in keyof ObjectType & (string | number)]: ObjectType[Key] extends object
? `${Key}` | `${Key}.${NestedKeyOf<ObjectType[Key]>}`
: `${Key}`;
}[keyof ObjectType & (string | number)];
// Type for all possible translation keys
export type TranslationKey = NestedKeyOf<Messages>;
+15
View File
@@ -0,0 +1,15 @@
{
"_comment": "Common UI strings shared across components",
"buttons": {
"createCommunityRule": "Create CommunityRule",
"seeHowItWorks": "See how it works",
"learnMore": "Learn more",
"askOrganizer": "Ask an organizer"
},
"ariaLabels": {
"followBluesky": "Follow us on Bluesky",
"followGitlab": "Follow us on GitLab",
"featureToolsAndServices": "Feature tools and services",
"askOrganizerContact": "Ask an organizer - Contact an organizer for help"
}
}
+8
View File
@@ -0,0 +1,8 @@
{
"_comment": "AskOrganizer component translations",
"title": "Still have questions?",
"subtitle": "Get answers from an experienced organizer",
"buttonText": "Ask an organizer",
"buttonHref": "#contact",
"ariaLabel": "Ask an organizer - Contact an organizer for help"
}
+30
View File
@@ -0,0 +1,30 @@
{
"_comment": "FeatureGrid component translations",
"title": "We've got your back, every step of the way",
"subtitle": "Use our toolkit to improve, document, and evolve your organization.",
"linkText": "Learn more",
"linkHref": "#",
"ariaLabel": "Feature tools and services",
"features": {
"decisionMaking": {
"labelLine1": "Decision-making",
"labelLine2": "support",
"ariaLabel": "Decision-making support tools"
},
"valuesAlignment": {
"labelLine1": "Values alignment",
"labelLine2": "exercises",
"ariaLabel": "Values alignment exercises"
},
"membershipGuidance": {
"labelLine1": "Membership",
"labelLine2": "guidance",
"ariaLabel": "Membership guidance resources"
},
"conflictResolution": {
"labelLine1": "Conflict resolution",
"labelLine2": "tools",
"ariaLabel": "Conflict resolution tools"
}
}
}
+31
View File
@@ -0,0 +1,31 @@
{
"_comment": "Footer component translations",
"organization": {
"name": "Media Economies Design Lab",
"email": "medlab@colorado.edu",
"url": "https://communityrule.com"
},
"social": {
"bluesky": {
"handle": "medlabboulder",
"ariaLabel": "Follow us on Bluesky",
"url": "https://bsky.app/profile/medlabboulder"
},
"gitlab": {
"handle": "medlabboulder",
"ariaLabel": "Follow us on GitLab",
"url": "https://gitlab.com/medlabboulder"
}
},
"navigation": {
"useCases": "Use cases",
"learn": "Learn",
"about": "About"
},
"legal": {
"privacyPolicy": "Privacy Policy",
"termsOfService": "Terms of Service",
"cookiesSettings": "Cookies Settings"
},
"copyright": "© All right reserved"
}
+9
View File
@@ -0,0 +1,9 @@
{
"_comment": "HeroBanner component translations",
"title": "Collaborate",
"subtitle": "with clarity",
"description": "Help your community make important decisions in a way that reflects its unique values.",
"ctaText": "Learn how CommunityRule works",
"ctaHref": "#",
"imageAlt": "Hero illustration"
}
+24
View File
@@ -0,0 +1,24 @@
{
"_comment": "NumberedCards component translations",
"title": "How CommunityRule works",
"subtitle": "Here's a quick overview of the process, from start to finish.",
"titleLg": "How CommunityRule helps",
"buttons": {
"createCommunityRule": "Create CommunityRule",
"seeHowItWorks": "See how it works"
},
"cards": {
"card1": {
"text": "Document how your community makes decisions",
"_comment": "First step card"
},
"card2": {
"text": "Build an operating manual for a successful community",
"_comment": "Second step card"
},
"card3": {
"text": "Get a link to your manual for your group to review and evolve",
"_comment": "Third step card"
}
}
}
+19
View File
@@ -0,0 +1,19 @@
import common from "./common.json";
import heroBanner from "./components/heroBanner.json";
import numberedCards from "./components/numberedCards.json";
import askOrganizer from "./components/askOrganizer.json";
import featureGrid from "./components/featureGrid.json";
import footer from "./components/footer.json";
import navigation from "./navigation.json";
import metadata from "./metadata.json";
export default {
common,
heroBanner,
numberedCards,
askOrganizer,
featureGrid,
footer,
navigation,
metadata,
};
+8
View File
@@ -0,0 +1,8 @@
{
"_comment": "Page metadata translations",
"home": {
"title": "CommunityRule - Build operating manuals for successful communities",
"description": "Help your community make important decisions in a way that reflects its unique values.",
"keywords": ["community", "governance", "decision-making", "operating manual"]
}
}
+6
View File
@@ -0,0 +1,6 @@
{
"_comment": "Navigation items",
"useCases": "Use cases",
"learn": "Learn",
"about": "About"
}
+56 -4292
View File
File diff suppressed because it is too large Load Diff
+1
View File
@@ -49,6 +49,7 @@
"critters": "^0.0.23",
"gray-matter": "^4.0.3",
"next": "^16.0.0",
"next-intl": "^3.26.5",
"react": "^19.0.0",
"react-dom": "^19.0.0"
},