Localization

Blocksweb provides robust localization features, allowing you to create multilingual content and experiences for your users. This system ensures that your applications can cater to a global audience while giving content editors fine-grained control over translations.

Default Localization

Blocksweb components can be designed to support multiple languages. When a component is rendered, it will first attempt to display content based on the currently selected language in the editor or the user's browser settings. If a translation for a specific language is not available, Blocksweb will fall back to a default localization, typically English, ensuring that content is always displayed.

This default behavior simplifies development, as you don't need to provide translations for every single language upfront. You can start with a default language and add more translations as needed.

Adding Your Own Localized Blocks

To create localized blocks or components, you typically use Options to define properties that can hold different values for different languages. For example, a text option for a title can have a different value for English, Spanish, or French.

When designing your components, consider how text and other content will vary by language. You can pass localized data to your React components as props, allowing them to render the appropriate content based on the active language.

Here's an example of a component with localization support:

import React from "react";
import { IBlockswebComponent } from "@blocksweb/core";

type LocalizedButtonProps = {
  buttonText: string;
};

const LocalizedButton: IBlockswebComponent = (props: LocalizedButtonProps) => {
  return (
    <button className="primary-button">
      {props.buttonText}
    </button>
  );
};

LocalizedButton.schema = {
  displayName: "Localized Button",
  options: [
    {
      type: "text",
      name: "buttonText",
      label: "Button Text",
      default: "Click Me", // Default English text
    },
  ],
};

export default LocalizedButton;

Overriding Translations in the Editor

Content editors have the ability to override default translations directly within the Blocksweb editor. This is done by:

1. Switching to a different language: The editor provides a language selector that allows content managers to change the active language view.
2. Updating the text: Once a new language is selected, any editable text fields (e.g., those configured with text or richtext options) will display the content for that language. Editors can then modify the text, and Blocksweb will save the updated translation for that specific language.

This process allows for dynamic content updates across multiple languages without requiring developer intervention for each translation.

Example Scenario

Imagine a HeroComponent with a title option.

• Developer Setup: The developer defines the title option in the component's schema.
• Default Content: The developer provides a default English title, e.g., "Welcome to Our Site".
• Editor Workflow:
  1. An editor views the page in English and sees "Welcome to Our Site".
  2. The editor switches the language to Spanish in the Blocksweb editor.
  3. The editor updates the title field to "Bienvenido a Nuestro Sitio".
  4. Blocksweb saves "Bienvenido a Nuestro Sitio" as the Spanish translation for that specific HeroComponent instance.

Now, when a user views the page, Blocksweb will display "Welcome to Our Site" for English speakers and "Bienvenido a Nuestro Sitio" for Spanish speakers.

Implementing Language Switching

In your frontend application, you can implement language switching functionality that respects the localized content created in the Blocksweb editor:

import React, { useState, createContext, useContext } from 'react';

// Create a language context
const LanguageContext = createContext({
  currentLanguage: 'en',
  setLanguage: (lang: string) => {}
});

// Language provider component
export const LanguageProvider = ({ children }) => {
  const [currentLanguage, setCurrentLanguage] = useState('en');
  
  const setLanguage = (lang) => {
    setCurrentLanguage(lang);
    // You might also want to store the preference in localStorage
    localStorage.setItem('preferred-language', lang);
  };
  
  return (
    <LanguageContext.Provider value={{ currentLanguage, setLanguage }}>
      {children}
    </LanguageContext.Provider>
  );
};

// Custom hook to use the language context
export const useLanguage = () => useContext(LanguageContext);

// Example language switcher component
export const LanguageSwitcher = () => {
  const { currentLanguage, setLanguage } = useLanguage();
  
  return (
    <div className="language-switcher">
      <button 
        className={currentLanguage === 'en' ? 'active' : ''} 
        onClick={() => setLanguage('en')}
      >
        English
      </button>
      <button 
        className={currentLanguage === 'es' ? 'active' : ''} 
        onClick={() => setLanguage('es')}
      >
        Español
      </button>
      <button 
        className={currentLanguage === 'fr' ? 'active' : ''} 
        onClick={() => setLanguage('fr')}
      >
        Français
      </button>
    </div>
  );
};

Best Practices for Localization

1. Plan for text expansion: Some languages require more space than others. Design your components with flexibility to accommodate text that may be 30-50% longer in some languages.

2. Use semantic keys: When creating your schema options, use semantic naming for properties rather than presentation-focused names (e.g., use welcomeMessage instead of headerText).

3. Consider cultural differences: Be mindful of cultural differences that might affect your design, such as reading direction (RTL vs LTR), date formats, and number formatting.

4. Test with real translations: Don't rely on placeholder text. Test your components with actual translations to identify potential layout issues.

5. Provide context for translators: When working with professional translators, provide context about where and how the text will be used to ensure accurate translations.

See Also

• Components - Learn how to create Blocksweb components that can utilize localization.
• Options - Understand how to define options that support multilingual content.
• Content Management - Explore how localized content is managed within the CMS.