Make your own pack

A pack is a .zip file of Japanese lines with furigana, word meanings and translations. Have an AI agent make one from a text, subtitles, comic pages or a script, then add it to Kotowa from the Files app.

https://kotowa.gellyfish.dev/make-a-pack.md

On this page: what the pack tool does, text, subtitles, comic pages, a script, adding the pack, video and what you may put in a pack. If you would rather write the JSON yourself, see the pack format.

What the pack tool does

The sections from here to adding the pack show the pack tool's inputs and commands; an agent follows the same layout. You give the tool the Japanese lines. For every line it adds furigana, romaji and a breakdown into words, each with a dictionary meaning from JMdict. It writes the result as a pack folder and as a .zip.

The tool does not translate whole sentences. If you want a sentence translation under a line, you give it, in the input file or in a separate translations file. Without one, a line still has its word-by-word meanings.

It runs on your own computer, and nothing is uploaded. Word meanings come in English and, if you ask for it, Spanish. Spanish uses the translation built into macOS, so build on a Mac if you want it.

Options every kind uses

When the tool finds something wrong it prints a line starting with error: or problem: that names the section, line or text, and it makes no zip.

From a text

Use this for a story, an article or any plain text. Save it as UTF-8 and write:

• one line per line of reading. A blank line ends an item, so lines you write together stay together under one translation;
• # Title on its own line to start a new section;
• nothing else. A line longer than 40 characters is cut after each sentence end.

# 朝

今日は雨だ。
傘を持って行こう。

駅まで歩いた。

# 夜

家に帰って、ご飯を食べた。

To add sentence translations, make a JSON file with a section's id, then an item's id, then a language. Sections are called part-1, part-2 and so on, in order (a text with no # Title, or only one, has a single section called text). Items are t1, t2 and so on within each section.

{
  "part-1": {
    "t1": { "en": "It is raining today. Let's take an umbrella." },
    "t2": { "en": "I walked to the station." }
  },
  "part-2": {
    "t1": { "en": "I went home and ate." }
  }
}

pack-tool --kind text --input story.txt --translations story-tr.json \
  --id my-story --title "My story" --license private --out output

Texts from Aozora Bunko work as they are: the tool understands their furigana (漢字《かんじ》) and drops the notes, the header and the footer. Aozora's files are Shift JIS, so convert one to UTF-8 first: iconv -f SHIFT_JISX0213 -t UTF-8 file.txt > story.txt. The demo pack 蜘蛛の糸 was made this way.

From subtitles

Use this for a video you have subtitles for, in SRT or ASS/SSA format with Japanese text. Each subtitle becomes one line, timed to the video, so Kotowa can play the video with the lines over it. There is one section, named after the video.

1
00:00:01,000 --> 00:00:03,500
おはよう。今日は天気がいいね。

2
00:00:04,000 --> 00:00:06,000
うん、散歩に行こうか。

Translations go in a JSON file as for a text. The section is called subtitles and the items are c1, c2 and so on, in the order of the subtitles.

{
  "subtitles": {
    "c1": { "en": "Good morning. Nice weather today." },
    "c2": { "en": "Yes, shall we go for a walk?" }
  }
}

pack-tool --kind subtitles --input scene.srt --translations scene-tr.json \
  --video-title "Morning walk" --video-url https://example.com/morning \
  --id morning-walk --title "Morning walk" --license private --out output

--video-title names the video in Kotowa, and --video-url is where a learner can get a copy, if there is such a place. The pack never contains the video. See video below. In an ASS file the speaker name column becomes the line's speaker. The demo pack Kizuna AI: SCP財団 was made this way.

From comic pages

Use this for manga or any picture with text. You type the text of each panel into a file, and the tool does not read it from the image. Each page becomes a section that shows the page image, and each panel becomes a line. Put the page images (PNG, JPEG, WebP or GIF) in a folder and list them in a YAML or JSON file:

pages:
  - image: page1.png
    title: 朝
    panels:
      - speaker: 太郎
        text: 今日は雨だ。
      - speaker: 花
        lines: ["傘を持って行こう。", "風も強いね。"]
        translations: { en: "Let's take an umbrella. It's windy too." }

• text is one line, lines several lines for one panel.
• speaker and translations are optional.
• title is the section's name; without it the section is called Page 1, Page 2 and so on.

pack-tool --kind comic --input pages.yaml --images pages \
  --id my-comic --title "My comic" --license private --out output

--images is the folder with the page images. Without it the tool looks beside the input file. The demo pack ブラックジャックによろしく was made this way.

From a script

Use this for a dialogue, a lesson or a transcript that says who says what. It is a list in YAML or JSON:

- speaker: 花
  text: すみません、駅はどこですか。
  translations: { en: "Excuse me, where is the station?" }
- speaker: 店員
  text: まっすぐ行って、右です。
  translations: { en: "Go straight, then it is on the right." }

Add start (and optionally end), in seconds, to time the lines against a video. Then every entry needs one. Without them the pack has no video.

pack-tool --kind script --input dialogue.yaml \
  --id station --title "At the station" --license private --out output

Add the pack to Kotowa

1. Get the .zip onto your iPhone or iPad: AirDrop it, or put it in iCloud Drive or any folder in the Files app.
2. In Kotowa, on the Library screen, tap Add pack and choose the .zip.
3. If a pack with the same id is already there, Kotowa asks whether to replace it. Say yes after you have rebuilt a pack.

Kotowa checks the whole pack before it adds anything. If something is wrong it says what, and nothing changes. To remove a pack, open it, go to Settings and tap Remove pack.

Video

A pack made from subtitles, or from a script with times, can play with a video, but it never holds the video: you link your own copy. Open a pack and tap Watch this … on a section. Kotowa asks you to link the video and you choose the file in Files. If the pack gave a --video-url, the dialog also offers a Get button for it.

Kotowa compares the chosen file's length with the one the pack expects, when the pack knows it, and asks before linking a file that differs by more than 5 seconds: it is probably another video, or another cut, and every line would be off. Use a file that iOS can play. An MP4 or MOV with H.264 video is the safe choice.

What you may put in a pack

A pack you add is yours, for your own use. Kotowa does not supply, host or share packs, and you are responsible for having the right to use what is in the ones you make. This is a guide, not legal advice, and the rules differ from country to country.

Content you can use freely or share

• Your own writing and translations.
• Works in the public domain, such as the older texts at Aozora Bunko. Check each text's notes: a modern edition's notes, pictures or recordings have their own rights.
• Works offered under an open license such as Creative Commons. Follow the license: give the credit it asks for, and note whether it lets you share changed copies on the same terms.
• Works whose owner has given you permission in writing.

Put the true license in --license and the credit in --credits. The three demo packs in Kotowa are examples of this.

Content for your own study only

For a book, a video, a comic or a game script that you have but do not have the right to share, use --license private. Keep that pack on your own devices. Do not post it, send it to others or put it on a server. Whether you may copy something you bought, for your own study, depends on your country and on the thing itself.

Please don't

• Share packs of material you have no right to share.
• Get content by breaking copy protection.
• Use someone's name, pictures or logos as if the pack came from them.

The pack tool runs on your computer, and your files stay there. Kotowa itself sends nothing anywhere; see the privacy policy.