Choose what text readers see

This page compares the content choices for Text Segment, Bilingual Segment, Source Card, and the Reader. It assumes that one of those components already works. If you don't, start with Put your first source on a page.

Terms

Three terms matter throughout:

• An edition is one specific published text on Sefaria. Its title names it, such as Bible du Rabbinat 1899 [fr].
• A language (or language family) is a group of editions, such as french. A language names many editions. A title names one.
• The primary edition is the one Sefaria marks primary for that text. It's usually the original, such as Hebrew.

A request is one call from the page to Sefaria. A dash in the tables means the component has no such attribute. The Reader also has attributes that aren't about text choice.

Each choice is an HTML attribute. You write it inside the tag.

Two kinds of changes

• Which text to load is the language and edition. These change what the component requests, so a change makes a new request.
• How it's shown is vocalization, sides, arrangement, and the edition credit. These redraw text the component already has and never make a request.

Choose which text to load

These choices change what the component requests.

You want to…	Text Segment	Bilingual Segment	Source Card	Reader
Show a translation in a language	translation-language
Show any edition in a language, including the original	version-language	—
Fall back when the language is missing	translation-fallback (default or none). Text Segment and Bilingual Segment default to none. Source Card and Reader default to default.
Pin an exact edition	version-title (see Pin an exact edition)	primary-version-title, translation-version-title

For the segments and Source Card, a fresh load makes one request. It makes two if the translation language is missing and translation-fallback is default. The Reader also loads the surrounding section and its links.

Supplied data on Text Segment, Bilingual Segment, or Source Card makes no request. See Give components your own data.

Choose a translation language

Set translation-language to a language name such as french. The value ignores case and outer spaces. All four components accept it. On Text Segment, it shows a translation instead of the primary edition, for example <sefaria-text-segment sref="Micah 6:8" translation-language="french">. It returns translations only. version-language can also return the original.

When Sefaria doesn't have that language

The chart above shows where the fallback happens. Set it with translation-fallback: default or none.

Not every text has every translation. Ask for french on Berakhot 2a:1. Sefaria's response warns that French is missing. The setting decides what happens next.

• default is the default for Source Card and Reader. The component makes one more request for Sefaria's default translation. That translation isn't always English. Source Card and Reader show a notice such as french is unavailable; showing english. For the text operation, a fresh load makes two requests. The Reader repeats this for its surrounding section and also requests links.
• none is the default for Text Segment and Bilingual Segment. The component makes no second request. It shows the status message "No french text." This isn't an error. Text Segment is empty. Bilingual Segment and Source Card show the primary side with status ready.

With fallback	What readers see	Requests
default	Sefaria's default translation, with a notice on Source Card and Reader	One more request
none	The status message "No french text."	No second request

With default, Text Segment and Bilingual Segment show the fallback text without a notice.

Only a bare language preference can fall back. An exact edition title never falls back, and an empty edition stays empty. In Bilingual Segment and Source Card, you can pin one side and give only a language for the translation. That translation can still fall back.

Pin an exact edition

To avoid a fallback, pin one edition by its title. A title picks one edition, while a language picks any edition in that group.

Choice	Picks	Can include the original	Falls back
translation-language	A translation in that language	No	Depends on translation-fallback
version-language	Any edition in that language	Yes	Never
Title attributes	One edition	Depends on the title	Never

• Bilingual Segment and Source Card: primary-version-title pins the primary edition. translation-version-title pins the translation.
• Text Segment: version-title alone chooses another edition in the original language, such as a different Hebrew edition. To choose a translation by title, also set translation-language.

On Text Segment, translation-language and version-language are mutually exclusive. Pick one. version-language alone doesn't pin one edition.

Choose how it's shown

These choices redraw text that has already arrived.

You want to…	Text Segment	Bilingual Segment	Source Card	Reader
Change Hebrew vowel marks and cantillation	vocalization-mode
Choose which sides show	— (one side)	content-language
Arrange the sides	—	layout, side-order
Hide the edition credit	—		hide-attributions

On the Reader, hide-attributions and the side attributes apply to its source card.

Source Card also has selectable. Switching sides makes no request, because all three components with sides request both sides even when they show one. Source Card makes one text request for the whole card, however many verses it shows. It makes a second request only when the fallback applies.

Set Hebrew vocalization

vocalization-mode controls the marks written with Hebrew letters. Hebrew text can carry vowel marks (nikkud) and cantillation marks (taamim). The default, taamim_and_nikkud, shows both. The other modes also remove related marks, such as the sof pasuq (׃). For exact behavior, see Change vowels and cantillation.

Value	Hebrew shown
taamim_and_nikkud	Vowel marks and cantillation
nikkud	Vowel marks, without cantillation
none	No vowel points or cantillation

All four components accept it.

Choose the sides and their arrangement

Sides and arrangement apply to Bilingual Segment, Source Card, and Reader.

• content-language is both, primary, or translation. The default is both.
• layout is auto, stacked, or side-by-side. The default is auto.
• side-order is primary-first or translation-first. The default is primary-first.

Two columns appear only when both sides show. side-order changes the visual order only in two-column layouts.

Try them together

Change the choices on a Source Card

Change the menus. Vocalization and sides redraw without a request. Choosing a translation language makes a new request. It makes two if Sefaria falls back.

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<form id="choices">
  <label>
    Translation language
    <select name="translation-language">
      <option value="">Sefaria's default</option>
      <option value="french">French</option>
      <option value="german">German</option>
    </select>
  </label>
  <label>
    Vowel marks
    <select name="vocalization-mode">
      <option value="taamim_and_nikkud">Vowels and cantillation</option>
      <option value="nikkud">Vowels only</option>
      <option value="none">None</option>
    </select>
  </label>
  <label>
    Sides
    <select name="content-language">
      <option value="both">Both</option>
      <option value="primary">Primary</option>
      <option value="translation">Translation</option>
    </select>
  </label>
</form>
<sefaria-source-card sref="Micah 6:8"></sefaria-source-card>
<script type="module">
  const card = document.querySelector("sefaria-source-card");
  document.querySelector("#choices").addEventListener("change", (event) => {
    const { name, value } = event.target;
    if (value) card.setAttribute(name, value);
    else card.removeAttribute(name);
  });
</script>

Edition credit and license

Only Source Card and Reader name the edition. They show each edition's title and language. They link the title to its source when Sefaria gives a valid http(s) address. They don't show the license. Text Segment and Bilingual Segment show only the text.

On Source Card, hide-attributions hides the credit and the fallback notice. It makes no request.

Generated client types include an optional license field in an edition's version metadata, but the components don't display it. Before you republish an edition, check its reuse rights. Look up its license, for example in the edition's details on Sefaria. This isn't legal advice.

Learn more: Install and status · Sefaria's own texts and tools

Clean up stored text

Vocalization changes only how text is shown. Cleaning stored text is a separate job for the text tools.

Learn more: Clean up stored Sefaria text · Reference › Text tools

Next steps

• Change how the components look with Match your site's look.
• See the full examples in Show one passage, Show Hebrew and translation together, and Show an attributed passage.
• Look up every attribute in Reference › Components, or read Reference › Client if you load text yourself.