README.md

sitelen pona UCSUR guide!!!

o sitelen e sitelen pona lon ilo mute a!

Render sitelen pona on most desktop applications!

Due to the standardization of codepoints in the UCSUR, you can now render sitelen pona on many desktop applications (Firefox, Discord, etc). In many applications all you need to do is install a UCSUR compatible sitelen pona font, and you are good to go. However there are some quirks, and you need an input engine to be able to easily input these characters, which is the purpose of this guide.

Fonts

The current recommended fonts for sitelen pona are:

• Fairfax HD

  

  This font by jan Lepeka (@rebeccargb) supports the latest (2024-02-20) version of UCSUR. It does not look a bit nasa, however it is mostly readable.

• nasin nanpa

  

  This is an alternative font, actively being developed by jan Itan (@etbcor). It is monospace, and supports cartouches, combination glyphs, and long glyphs (pi, tawa & lon). This font supports the 2024-02-20 version of UCSUR, and is used in su!

• sitelen seli kiwen juniko (mono)

  

  This font by jan Lepeka (@rebeccargb) supports the most recent version of UCSUR (2024-02-20). It's personally my favorite! There are proportional (glyphs take up varying amounts of space) and monospaced (glyphs take up the same amount of space) versions of the font. Monospaced fonts in general are recommended for sitelen pona (both of the above fonts are monospaced). sitelen seli kiwen juniko mono, the monospaced version of sitelen seli kiwen juniko is used in the css below, fyi.

If you are unsure of which font to pick, I would recommend nasin nanpa.

Once you have installed any of these fonts you are done, in many applications sitelen pona should render correctly, with the exception of websites, as they do not fall back to sitelen pona. This is an issue, because some applications are actually websites, with a notable example being Discord.

Discord

Because internally the Discord application relies on Electron, it does not fall back to the font you installed when sitelen pona glyphs are present, instead displaying these frustrating little squares. To fix this, one option is to install a fake Helvetica Neue font, which will allow sitelen pona to render wherever Helvetica Neue is used, which includes Discord!

Another option is to modify your Discord. Currently, this modification is possible on all Desktop systems. This option is dangerous, violates Discord TOS, and may result in your account being banned.

Font

Simply install the fake Helvetica Neue font, and it should result in Discord displaying UCSUR.

For Windows,

• Download and install this font

For Linux,

• Download the above font
• Copy the file to ~/.local/share/fonts/

This method does not work on macOS or mobile devices.

Desktop

⚠️⚠️⚠️ THIS VIOLATES DISCORD'S TOS. O SONA A ⚠️⚠️⚠️

If you use BetterDiscord...

1. Download the sitelen pona theme: https://raw.githubusercontent.com/neroist/sitelen-pona-ucsur-guide/main/css/sitelen-pona.theme.css

2. In Discord, go to your BetterDiscord settings and select the Themes tab.

3. At the top click the "Open themes Folder" button (either as a large blue button or the small folder icon near the top)

4. Move the file you downloaded into this folder.

5. Go back to your Themes page and enable the theme.

To patch your Discord to correctly render sitelen pona on desktop, we will use the Vencord client modification. Start by following the installation guide on their website to install it. After installing Vencord we need to add a CSS snippet, a small snippet of code that tells Vencord to use Fairfax HD or nasin nanpa when sitelen pona is present.

First go to go to Settings, then scroll down to "Vencord", click "Themes", then "Online Themes"

Paste this link into the text box:

https://raw.githubusercontent.com/neroist/sitelen-pona-ucsur-guide/main/css/sitelen-pona.theme.css

If the "Validator" section below shows that the theme is valid, you can now exit settings, and your Discord should be properly set up to render sitelen pona!

Browser

If you use a web browser, you can use the stylus extension to help render sitelen pona.

Simply install this userstyle and you're done!

Android

This reddit post by jan Elijo (u/QuantumAgain) is a wonderful guide on how to get UCSUR on Android. Regarding viewing sitelen pona, here are the listed steps:

⚠️ note: this changes the system font to something else, if you want to only view sitelen pona on Discord please use Aliucord (the next section)

List format for instructions (zFont systemwide)

Installing the font:

1. Download nasin-nanpa-4.0.0-UCSUR.otf or the latest UCSUR version from the nasin-nanpa releases page.

2. Convert nasin-nanpa-4.0.0-UCSUR.otf to nasin-nanpa-4.0.0-UCSUR.ttf (If you're not sure how, skip this step or click the link.)

3. Download zFont 3 from the Play Store. (Other font changing apps such as #mono_ might work instead)

4. In the app, go to Downloads, press the + icon in the bottom right and add the font file (select "Add File"). (If you didn't convert it, the app will prompt you to install another app and you can do it there if you need).

5. Click on the font file and press Apply.

6. The app will ask you for your Android version, choose "Auto".

7. Follow the steps in the app, they vary depending on your phone, for me it involved installing a fake Samsung font.

8. Once you're done you should now be able view sitelen pona in every app.

You should be able to read this: 󱥞󱤘󱤮󱤉󱥁

jan Nasaka (@harger lon ilo Siko) li pana e sona ni tawa mi. ona li pona mute a! :)

The above method may not be supported on your device. One alternative is to use the Aliucord Discord client and set a custom font. (This method causes small font discrepancies in the Aliucord client). The setup instructions are below:

List format for instructions (Aliucord)

1. Install Aliucord from its Github page

   • Please follow the installation instructions in the readme

2. Install the Themer plugin, which will allow you to change Aliucord's font.

   • One method for doing this is pasting in the zip link (https://github.com/Vendicated/AliucordPlugins/blob/builds/Themer.zip?raw=true) into a Discord message, then clicking the link in Aliucord.

3. In Aliucord, go to User Settings (click your pfp in the botton right) -> Plugin Settings (near the bottom) -> Themer and toggle Enable Custom Fonts.

4. Click New Theme, enter a name for your new theme, toggle the theme, and click the pencil icon on your theme to edit it.

5. On the new menu click the Fonts button, then click the * and paste in this link: https://github.com/ETBCOR/nasin-nanpa/releases/download/n4.0.1/nasin-nanpa-4.0.1-UCSUR.otf.

   This is nasin-nanpa, which is the font that'll allow you to view sitelen pona

6. Click off the popup, then press the save button in the bottom right. When it prompts you to restart, restart.

7. pini a! sitelen pona la o lukin pona

iOS

to view sitelen pona in Discord, jan Nasaka (@harger lon ilo Siko) has written a bash script to download and merge the latest versions of the Enmity Discord client and the font nasin-nanpa into a .ipa app file. A premerged .ipa file can be found here.

For installation instructions not requiring a jailbroken device, please refer to the "Sideloading Apps" section on this page.

Input

Now that sitelen pona is rendering properly, we need to be able to type it!

Windows

There are three input engines for Windows: nasin Ajemi, nasin AHK, and Keyman

You can download & install nasin Ajemi from this link, see the README on how to use it.

For nasin AHK, there is an Auto Hotkey Script (download with Ctrl+S) by jan Itan (@etbcor) for input. Write the toki pona word and then a ` (the letter under escape) to convert it into sitelen pona. You can also write [` and ]` for cartouches, as well as (` and )` for long glyphs. There is also a "small" version of the script that uses 3 letter codes for each word instead of typing the whole word.

For this of this to work, you need to have Auto Hotkey installed.

Other features of the script are explained in this README file.

For Keyman, jan Lepeka (@rebeccargb) has made keyboards for various toki pona input methods. For install instructions, refer to the #Keyman section.

macOS

jan Tepo (@tbodt) has made an input plugin for macOS with modifications by jan Semu (@jmiibo) to support UCSUR (download with Ctrl+S). Download it, then install it by double clicking. Then enable it in System Preferences -> Keyboard -> Input Sources. You'll find it listed under "Chinese, Simplified".

jan Lepeka (@rebeccargb) has made keyboards for various toki pona input methods. For install instructions, refer to the #Keyman section.

Linux

The only (nasin sitelen Wakalito li lon · ilo ante kin li lon) current supported input engine for Linux is ibus, for this to work, you need both ibus, and ibus-tables installed. For installation commands/instructions, see this page.

During installation, regarding Ubuntu, feel free to remove ibus-qt4 from the apt-get insall command, which has been removed from Ubuntu's main repository.

jan Komi (@cominixo) has created an ibus input table (click the link & download with Ctrl+S). Copy it to a directory of your choice, and then open a terminal in the same directory. Run these commands to install it:

sudo ibus-table-createdb -n /usr/share/ibus-table/tables/tokipona.db -s sitelen-pona-4.0.ibus-table
ibus-daemon -drxR

Once you have done this, open the ibus preferences (you can do this with the ibus-setup command). Go to Input Method, click Add and then select sitelen pona (the last option under the English category).

Finally, if necessary, go to your keyboard settings in your settings application and add a "sitelen pona" input source (the name should be "English (sitelen pona)").

This should result in a new tray icon which indicates which input source you're using—English or sitelen pona. Which keybinding which allows you to switch input sources may depend on your distro. However, on Pop!_OS it is Super + Space

List format for instructions

1. Install ibus and ibus-tables. Follow the instructions on this page.

   • For Ubuntu, do not install the ibus-qt4 package

2. Download the ibus input table here.

3. Copy the file to a chosen directory and open a terminal in the directory

4. Run these two commands:

sudo ibus-table-createdb -n /usr/share/ibus-table/tables/tokipona.db -s ibus-tables/sitelen-pona-4.0.ibus-table

ibus-daemon -drxR

5. Open ibus preferences (you may run the ibus-setup command)

6. Add the sitelen pona input method. Go to Input Methods -> Add -> English -> (scroll all the way down to) sitelen pona

7. If needed, go to your settings application and add a new input source of the name "English (sitelen pona)"

   • Feel free to search for "sitelen pona" and select anything similar, if "English (sitelen pona)" is not present

8. Switch input sources (either via keybindings or the tray icon).

9. pini a!

Espanso / nasin sitelen Wakalito

nasin Wakalito is an input method for writing Toki pona words. It is available on macOS, Linux, and Windows using Espanso. By default, nasin Wakalito outputs words in sitelen Lasina. However, by using a modified config file, we can output UCSUR instead.

In addition, if you just need/want to use Espanso and don't like the triggers in nasin Wakalito, there is also a config file for that (sitelen-pona-espanso.yml).

nasin:

1. Install Espanso here

2. Download a config file. There are two:

   • This file uses nasin Wakalito's triggers, and outputs UCSUR

   • This file uses toki pona word triggers, and outputs UCSUR

3. Copy or move the file to Espanso packages folder

   • Windows: C:\Users\<user>\AppData\Roaming\espanso\match\packages

     • (Win+R, type %appdata% to get to \Roaming

   • macOS: /Users/<user>/Library/Preferences/espanso/match/packages

   • Linux: ~/.config/espanso/match/packages

4. From where you've found your Espanso packages folder (<wherever>/espanso/match/packages), navigate to <wherever>/espanso/config and open the file default.yml in a text editor

5. On a new line, paste the text toggle_key: RIGHT_ALT, then save your changes and exit

6. Start Espanso

7. Start writing! (When you want to toggle Espanso on/off, double tap Alt on the right side of your keyboard!)

   • A table for triggers -> words can be found on sona.pona.la, here, with a few modifications listed below. This is for the first config file, wakalito-7-3-2-ucsur.yml.

Modifications

Character	Keys on a QWERTY layout
(fullwidth space)	666, (3 spaces)
‍ ("-" zero width joiner)	aa
󱦕 ("^" stacking joiner)	gg
󱦖 ("*" scaling joiner)	hh
󱦝 (":" sp colon)	6y
󱦜 ("·" sp dot)	3
󱦐 ("[" cartouche start)	c1
󱦑 ("]" cartouche end)	c2
「 (cjk start quote)	q1
」 (cjk end quote)	q2
󱦗 ("(" start left-combining long glyph)	b1
󱦘 (")" end left-combining long glyph)	b2
󱦚 ("{" start right-combining long glyph)	d1
󱦛 ("}" end left-combining long glyph)	d2

Keyman

Keyman is an input engine created by the Summer Institute of Linguistics, which allows for user-designed keyboards and, by extension, input methods. It is available on Windows, MacOS, Linux, iOS, iPadOS, Android, and in web browser. Four sitelen pona keyboard layouts, implemented by jan Lepeka (@rebeccargb), are listed below:

• For a sitelen pona taso keyboard, you can use:

  • jan Lepeka's (@rebeccargb) Sitelen Pona (KreativeKorp, UCSUR).
  • jan Komi's (@cominixo) Sitelen Pona (Pochin, UCSUR).
  • jan Likipi (@lilscribby), kala pona Tonyu's (@bucketfish), and jan Tepo's (@tbodt) Sitelen Pona (Wakalito, UCSUR).

• For a Latin keyboard, you can use jan Lentan's (@slashdevslashurandom) Sitelen Pona (Lentan, UCSUR).

Installation instructions are listed below by platform:

Windows instructions

1. Go to Keyman's download download page and click the green Download Now button.

2. A file named keyman-<version>.exe will download. Open it.

3. Click Install, then Configuration, then Download Keyboard... in the bottom left corner.

4. On the new window, click Enter language or keyboard, and type "Sitelen Pona".

5. A list of keyboards will appear. Click on your desired input method, then click Install keyboard -> Install -> Yes -> Yes.

6. A new window will pop up explaining the input method, regard it, then press OK.

7. Close the window titled "Keyman Configuration," and, in the first Keyman window that opened, click Start Keyman.

   • To toggle through input methods, press Windows+Space bar.
   • To toggle an onscreen version of your keyboard, press Shift+Alt+K.

8. o sitelen pona!

MacOS instructions

1. Go to Keyman's download page and click the green Download Now button.

2. A file named keyman-<version>.dmg will download. Open it.

3. Double click the Keyman icon.

4. A new window will pop up with a generic 3rd party software warning. Click Open -> Install -> OK.

5. Your System Settings app will open, prompting you to enable Keyman. Click OK.

6. On your toolbar, a new icon will appear showing your current "input source." Click it, set your input source to Keyman, then click Configuration....

7. In your new window titled "Keyman Configuration," click Download Keyboard....

8. On the new window, click Enter language or keyboard, and type "Sitelen Pona".

9. A list of keyboards will appear. Click on your desired input method -> Install keyboard -> Done.

10. Your sitelen pona input method will be listed under the "Keyman" section in your toolbar input menu. Click it to enable it.

    • You can toggle your default input method at any time in the toolbar input menu.

11. To see an explanation of your input method, open the dropdown, and click Configuration.... A window will pop up explaining your input method under the "Read Me" tab.

12. o sitelen pona!

Android and iOS instructions

1. Install the app:

   • On iOS, Install Keyman from the App Store
   • On Android, install Keyman from the Google Play Store

2. Open the app and click the ◦◦◦ button on top right corner.

3. A window titled "Get Started" will open. Click the button in the middle titled "Set up Keyman as system-wide keyboard" or "Enable Keyman as system-wide keyboard."

4. On the new window, toggle Keyman as a keyboard.

   • On iOS, under the section titled "PREFERRED LANGUAGE" click Keyboards and toggle Keyman.
   • On Android, toggle Keyman. A privacy popup will appear, regard it, then press OK -> OK.

5. Navigate back to the Keyman app, click ◦◦◦ -> Settings -> Installed Languages -> +.

6. On the new window, click Enter language or keyboard, and type "Sitelen Pona".

7. An list of keyboards will appear. Click on your desired input method.

8. On the next page, click Install keyboard -> Install -> Done.

9. Swap to the Keyman keyboard and press the keyboard's globe icon to change to your sitelen pona input method.

10. o sitelen pona!

web browser instructions

1. Go to the Keyman keyboard search page and search for "Sitelen Pona".

2. A list of keyboards will appear. Click on your desired input method.

3. On the next page, click Use keyboard online, then, under the section titled "Browser Add-in", right-click the button Toki Pona Keyboard and add it to your bookmarks.

4. On most pages tested, clicking your new bookmark will load your sitelen pona input method.

   • If your keyboard uses an alternate layout, you can click the button Show On Screen Keyboard on the edge of a focused text box to view its layout.

5. o sitelen pona!

Android

Three input engines for android exist:

• jan Lepeka's (@rebeccargb) Keyman keyboards (refer to the #Keyman section)

• jan Komi's (@cominixo) (similar anu better APKs can be found in this reddit post)

  • When trying to install the APK, if you get an error that you cannot due to "package conflicts," delete the other Toki Pona Keyboard app and try again.

• and kulupu Mimuki's (@.mouseless) which can be used with this app, but it requires a paid addon to import the file.

iOS

Two input engines for iOS exist: Keyman, with jan Lepeka's (@rebeccargb) keyboards, and a fork of nasin sitelen Wakalito.

For instruction on installing Keyman sitelen pona keyboards, refer to the #Keyman section.

nasin sitelen Wakalito is an app created by jan Likipi (@lilscribby), kala pona Tonyu (@bucketfish), and jan Tepo (@tbodt). It uses Lipamanka's (@lipamanka) font, linja lipamanka. A fork of the app exists which changes its output to sitelen pona. The project files for this can be found here and the latest prebuilt .ipa app file can be found here. This fork of the app is maintained by jan Nasaka (@harger lon ilo Siko).

• For installation instructions not requiring a jailbroken device, please refer to the "Sideloading Apps" section on this page.

• A table for triggers -> words can be found on sona.pona.la, here, with modifications listed below.

List format for modifications

Formatting Modifications

Character	Keys on nasin Wakalito layout
(fullwidth space)	-
‍ (zero width joiner)	---
󱦕 (stacking joiner)	•^>
󱦖 (scaling joiner)	•<v
󱦝 (sp colon)	:
󱦜 (sp dot)	•
󱦐 (cartouche start)	[
󱦑 (cartouche end)	]
「 (cjk start quote)	▢[
」 (cjk end quote)	▢]
󱦗 (start left-combining long glyph)	[[
󱦘 (end left-combining long glyph)	]]
󱦚 (start right-combining long glyph)	[[[
󱦛 (end left-combining long glyph)	]]]

nimi sin Modifications

Character	Keys on nasin Wakalito layout
󱥸 (namako)	<v‴, ‴<v, □•, •□
󱦢 (majuna)	-‴-, ‴--
󱦤 (linluwi)	ooo^>-, ^>-ooo, |-||•••ᴗᴖ, |-||ᴗᴖ•••, |-|•••ᴗᴖ|, |-|ᴗᴖ|•••
󱦥 (kiki)	^>-^>-, -^>-^>-, ^>^>^>^><v<v<v<v, ^>^>^><v<v<v
󱦦 (su)	▢<v
󱦮 (owe)	‴o•

Additionally, triggers were removed for ASCII art, a Discord command, and words without sitelen pona characters in the font nasin-nanpa (unu, Pingo, oke, mulapisu, kapesi, and isipin).

Web

If you are on a device which cannot use these input methods for any reason, jan Tala (@at) has created a web based converter from sitelen Lasina to sitelen pona.

A sitelen pona Keyman bookmark can be used for inputting sitelen pona in a web browser. For instructions, refer to the #Keyman section.

End

This is a really huge step for toki pona, and I am extremely happy to see this happen. If you have created a font, input method, or any other resource that you want added, please create a pull request, issue, or just ping me on discord @o.v (jan Lili lon ma pona pi toki pona) and we can talk!

*~ tan jan Lili*

ijo pona

thank you to

• jan Komi
• kulupu Mimuki
• jan Tala
• soweli pona Tesa
• mun Kekan San
• jan Tepo
• jan Itan
• jan Lili
• jan Semu
• ijo @Qwerty-Space (lon lipu github)
• ijo @ReveredOxygen
• kulupu katu
• kule Piton
• ijo @gustav-langer
• jan Nasaka (@harger lon ilo Siko)
• jan Lepeka
• kala pona Tonyu
• jan Likipi
• Lipamanka
• tonsi Lijonala (@not_your_mpdg lon ilo Siko; @0x3444ac53 lon lipu Githun)

sina ale li pona wawa a li pana sona e pona anu pali pona a (anu ni tu a a)