Show Hebrew and translation together

The Bilingual Segment, <sefaria-bilingual-segment>, shows one passage in two editions at once: the primary text and a translation. You choose the layout, the side order, and the translation language. You can also choose the exact edition for each side.

Show a passage in two editions

Set sref to the reference. The component asks Sefaria once for two editions:

• The primary edition, which is the edition Sefaria marks isPrimary. It is usually, but not always, the Hebrew or original text. For Micah 6:8 it is "Miqra according to the Masorah".
• Sefaria's default translation. For Micah 6:8 it is "THE JPS TANAKH: Gender-Sensitive Edition".

The component shows only the text. It doesn't name the editions or show a license. For a credit line, use Source Card.

Hebrew and translation

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<sefaria-bilingual-segment sref="Micah 6:8"></sefaria-bilingual-segment>

Choose sides, layout, and editions

Set these attributes on the element. Add them one at a time and choose Run to see each change.

Attribute	Values (default first)	What it changes	Changes what's requested?
content-language	both, primary, translation	Which sides show.	No
layout	auto, stacked, side-by-side	Two columns need both sides (content-language="both"). auto uses two columns when the component is 500px wide or more, and one column below that. stacked is always one column. side-by-side is always two columns.	No
side-order	primary-first, translation-first	Visual order in two-column layouts only. Stacked layouts and screen-reader order keep the primary side first.	No
translation-language	A full lowercase language-family name, such as french	The language you want for the translation.	Yes
translation-fallback	none, default	What happens when Sefaria has no text in your preferred language. See Preferred language or exact edition.	Yes. Changing it starts a new request. default can add a second request when the language is missing.
primary-version-title	An exact edition title	The exact primary edition. It never falls back.	Yes
translation-version-title	An exact edition title	The exact translation edition. It never falls back.	Yes

For every attribute, including vocalization-mode, see Reference › Components. For the styling settings that every component shares, see Show one passage.

The first element below reads side by side with the translation first, in an exact JPS 1917 edition, with vowel points but no cantillation (vocalization-mode="nikkud"). The second stacks the sides and asks for a French translation.

Layout, order, editions and language

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<sefaria-bilingual-segment
  sref="Micah 6:8"
  layout="side-by-side"
  side-order="translation-first"
  translation-version-title="The Holy Scriptures: A New Translation (JPS 1917)"
  vocalization-mode="nikkud"
></sefaria-bilingual-segment>
<sefaria-bilingual-segment
  sref="Micah 6:8"
  layout="stacked"
  translation-language="french"
></sefaria-bilingual-segment>

Learn more: Choose what text readers see · Clean text and safety

Preferred language or exact edition

The two ways of choosing a translation behave differently:

• Preferred language (translation-language) asks for the best edition in that language. A fresh load makes one request. If Sefaria has no text in that language, what happens next depends on translation-fallback:
  • none is the default. The primary side shows. The translation side shows a note such as No french text., and screen readers read it too. There is no error and no more requests.
  • default makes one more request for Sefaria's default translation. That translation isn't always English, and the component shows no notice that it is a fallback. The total is two requests.
• Exact edition (translation-version-title, primary-version-title) asks for that title only and never falls back.

Both examples ask for French on Berakhot 2a:1. The first leaves translation-fallback at its default, none. The second sets translation-fallback="default".

A language Sefaria doesn't have

The first element shows the primary text and No french text. (one request). The second shows the primary text and Sefaria's default translation (two requests).

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<!-- Default: no fallback -->
<sefaria-bilingual-segment
  sref="Berakhot 2a:1"
  translation-language="french"
></sefaria-bilingual-segment>
<!-- Fallback to Sefaria's default translation -->
<sefaria-bilingual-segment
  sref="Berakhot 2a:1"
  translation-language="french"
  translation-fallback="default"
></sefaria-bilingual-segment>

When a side has no text

A side with no text shows a short note, such as No translation text is available. or No french text. The other side still shows. An edition that exists but has empty text doesn't trigger a fallback. To choose editions and vocalization for a single side, see Show one passage.

When there's nothing to show

Situation	status	Error event
Waiting for Sefaria. A loading message shows	loading	No
Sefaria can't be reached	error	Yes, sefaria-bilingual-segment-error
Sefaria says the text isn't a reference, or supplied data is invalid	error	No
One side has no text, so it shows a short note and the other side still shows	ready	No
No sref and no data, or neither side has text	empty	No

A failed load keeps the text already showing. Read status from the element in JavaScript. It is empty, loading, ready, or error. When Sefaria can't be reached, status is error and the error event fires, whether or not text was already showing. The event bubbles and crosses the component boundary. Its event.detail holds { error, sref }. It reports failed loading only. It doesn't report Sefaria's handled messages or invalid supplied data.

For every event, see Reference › Components.

The example has a good reference, a text that isn't a reference, and an empty element. Choose Show each status to log each one's status.

Read status and listen for errors

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<sefaria-bilingual-segment sref="Micah 6:8"></sefaria-bilingual-segment>
<sefaria-bilingual-segment sref="Not a book 3:4"></sefaria-bilingual-segment>
<sefaria-bilingual-segment></sefaria-bilingual-segment>
<button type="button" id="check">Show each status</button>
<pre id="log"></pre>
<script type="module">
  const log = document.querySelector("#log");
  document.addEventListener("sefaria-bilingual-segment-error", (event) => {
    log.textContent += `Error for ${event.detail.sref}: ${event.detail.error.message}\n`;
  });
  document.querySelector("#check").addEventListener("click", () => {
    for (const element of document.querySelectorAll(
      "sefaria-bilingual-segment",
    )) {
      log.textContent += `"${element.sref}" is ${element.status}\n`;
    }
  });
</script>

For all the empty states, see Bilingual Segment.

Learn more: Troubleshoot a page · Component events

Use your own data

If you already have Sefaria's text response, set the element's data property to it. The element then makes zero requests. See Give components your own data.

Next steps

• Show an attributed passage to link each edition to its source.
• Sefaria's own texts and tools to see how these choices compare with sefaria.org.
• Reference › Components for every attribute.