CSG Chamorro 🌴

Learn Chamorro words and phrases with your Ruby projects! A gem built by Code School of Guam students to preserve and share the Chamorro language.

🎉 Now published on RubyGems.org! Install with: gem install csg_chamorro

• Why This Gem?
• What's Included
• Project Structure
• Installation
• Usage
• Examples
• Testing Locally
• Development
• Contributing
• Publishing

The Chamorro language is an important part of Guam's cultural heritage. This gem helps:

• Preserve the language through technology
• Share Chamorro words with developers worldwide
• Learn basic Chamorro phrases in an accessible way
• Integrate language learning into daily development work

The gem includes 12 common Chamorro words and phrases:

1. Håfa Adai - Hello
2. Si Yu'os Ma'åse' - Thank you
3. Inafa'maolek - Harmony/To make good
4. Biba - Long live/Hurray
5. Hågat - Hello (casual)
6. Adios - Goodbye
7. Pågo - Now
8. Guåhan - Guam
9. I Manåmko' - The elders
10. Nåna - Mother
11. Tåta - Father
12. Hafa tatatmanu hao? - How are you?

Each word includes:

• Chamorro spelling
• English translation
• Pronunciation guide
• Usage context
• Example sentence

Understanding what each file and folder does:

csg_chamorro/
├── lib/                              ← Your Ruby code lives here
│   ├── csg_chamorro.rb              ← Main file with all the methods
│   └── csg_chamorro/
│       └── version.rb                ← Just the version number (0.1.0)
│
├── bin/                              ← Executable command-line tools
│   └── csg_chamorro                  ← The CLI script (runs when you type 'csg_chamorro')
│
├── test/                             ← Automated tests
│   └── csg_chamorro_test.rb         ← Tests all the methods work correctly
│
├── csg_chamorro.gemspec              ← Gem metadata (name, version, description, etc.)
├── Gemfile                           ← Lists dependencies (what other gems this needs)
├── Gemfile.lock                      ← Locks exact versions of dependencies
├── Rakefile                          ← Defines tasks you can run (rake word, rake list, etc.)
├── README.md                         ← Documentation (this file!)
└── LICENSE.txt                       ← MIT License (how others can use your code)

lib/ - The main code

• This is where your actual Ruby code lives
• lib/csg_chamorro.rb is the "entry point" - it's what runs when someone does require 'csg_chamorro'
• lib/csg_chamorro/version.rb stores the version number
• Ruby convention: main file name matches the gem name

bin/ - Command-line executables

• Contains scripts that users can run from the terminal
• bin/csg_chamorro is the CLI tool
• After installing the gem, typing csg_chamorro in terminal runs this file
• Must start with #!/usr/bin/env ruby (tells system to run it with Ruby)

test/ - Automated tests

• Contains test files that verify your code works
• test/csg_chamorro_test.rb has 11 tests
• Run with: ruby test/csg_chamorro_test.rb
• Uses Minitest framework (comes with Ruby)

csg_chamorro.gemspec - Gem specification

• Tells RubyGems everything about your gem
• Name, version, authors, description
• What files to include in the gem package
• What dependencies it needs
• Required for building the gem

Gemfile - Dependency management

• Lists gems your project depends on
• In our case, just says gemspec (use dependencies from .gemspec)
• Run bundle install to install dependencies
• Creates Gemfile.lock with exact versions

Rakefile - Task definitions

• Defines shortcuts for common tasks
• rake word - print a random word
• rake list - list all words
• rake test - run tests
• rake version - show version
• Like npm scripts, but for Ruby

README.md - Documentation

• First thing people see on GitHub
• Explains what the gem does
• Shows how to install and use it
• Includes examples

LICENSE.txt - Legal stuff

• MIT License (very permissive)
• Says others can use, modify, and share your code
• Required if you publish to RubyGems.org

This gem is published on RubyGems.org! Anyone can install it:

gem install csg_chamorro

Or add to your Gemfile:

gem 'csg_chamorro'

Then run bundle install.

📝 Note for students: This reference gem is already published, so you can install it right away! However, when you create YOUR own gem, it won't be installable via gem install until you publish it to RubyGems.org (see "Publishing" section below). Until then, test it locally using the "Testing Locally" section!

require 'csg_chamorro'

# Get a random Chamorro word
word = CSGChamorro.word_of_day
puts word[:chamorro]  # => "Håfa Adai"
puts word[:english]   # => "Hello"
puts word[:pronunciation]  # => "half-a-day"

# Get a nicely formatted word
puts CSGChamorro.pretty
# => 
# 📚 Chamorro Word of the Day
# 
# Chamorro: Håfa Adai
# English: Hello
# Pronunciation: half-a-day
# Usage: Traditional Chamorro greeting used throughout the day
# Example: "Håfa Adai! Welcome to Guam!"

# Get all words
all_words = CSGChamorro.all_words  # => Array of 12 words

# Count total words
CSGChamorro.count  # => 12

# Search for a word
results = CSGChamorro.search("thank")
# => [{chamorro: "Si Yu'os Ma'åse'", english: "Thank you", ...}]

# Get a random greeting
greeting = CSGChamorro.random_greeting

# Random word of the day
csg_chamorro
# => Håfa Adai - Hello

# Formatted output
csg_chamorro --pretty
# => Full formatted output with pronunciation and example

# Show all words
csg_chamorro --all

# Count words
csg_chamorro --count
# => Total Chamorro words: 12

# Get a random greeting
csg_chamorro --greeting

# Search for a word
csg_chamorro --search "hello"

# Help
csg_chamorro --help

require 'csg_chamorro'

# Print a Chamorro word every time you open your terminal
# Add to your ~/.zshrc or ~/.bashrc:
# ruby -e "require 'csg_chamorro'; puts CSGChamorro.pretty"

require 'csg_chamorro'

# Send a Chamorro word to your team Slack
word = CSGChamorro.word_of_day
message = "🌴 Chamorro Word of the Day: #{word[:chamorro]} (#{word[:english]})\n" \
          "Pronunciation: #{word[:pronunciation]}\n" \
          "#{word[:usage]}"
# send_to_slack(message)

require 'csg_chamorro'

# Quiz yourself on Chamorro words
word = CSGChamorro.word_of_day
puts "What does '#{word[:chamorro]}' mean?"
# ... get user input ...
puts word[:english]

Want to test this gem before installing? Here's how:

# Navigate to the gem folder
cd csg_chamorro

# Open IRB
irb

Then load and test the gem:

# Load the gem
require './lib/csg_chamorro'

# Test the methods
CSGChamorro.word_of_day
CSGChamorro.pretty
CSGChamorro.search("hello")
CSGChamorro.random_greeting

ruby test/csg_chamorro_test.rb

Should see: 11 runs, 15 assertions, 0 failures

bundle install   # First time only
rake word        # Random word
rake list        # All words
rake version     # Show version
rake test        # Run tests

# Build the gem
gem build csg_chamorro.gemspec
# Creates: csg_chamorro-0.1.0.gem

# Install it
gem install ./csg_chamorro-0.1.0.gem

# Test it works
csg_chamorro --pretty

After checking out the repo:

bundle install
bundle exec rake -T  # See available tasks

Run tests:

ruby test/csg_chamorro_test.rb

Build and install locally:

gem build csg_chamorro.gemspec
gem install ./csg_chamorro-0.1.0.gem

We welcome contributions from everyone! Whether you're a student, a Chamorro language speaker, or just someone interested in preserving indigenous languages, your help is appreciated! 🌴

We currently have 12 words, but there are so many more to share!

How to add words:

1. Fork the repository
2. Open lib/csg_chamorro.rb
3. Add a new word to the WORDS array following this format:

   {
     chamorro: "Your Chamorro word",
     english: "English translation",
     pronunciation: "how-to-say-it",
     usage: "When and how it's used",
     example: "Example sentence showing usage"
   }

4. Submit a pull request with your changes!

Ideas for words to add:

• Common greetings and phrases
• Family terms (siblings, grandparents, etc.)
• Numbers (one, two, three...)
• Days of the week
• Food and cooking terms
• Nature and animals
• Actions and verbs

Help make our pronunciation guides clearer! If you're a native speaker or have better phonetic knowledge, we'd love your input.

Help us ensure accuracy by adding more test cases in test/csg_chamorro_test.rb.

Found a mistake in spelling, pronunciation, or usage? Please let us know or submit a fix!

Open an issue to suggest:

• New features (search by category, difficulty levels, etc.)
• Additional word metadata (parts of speech, cultural context)
• Better examples or usage explanations
• Integration ideas

• Be respectful of the Chamorro language and culture
• Verify accuracy - if you're not sure about a word, ask or provide sources
• Follow the existing format to keep the gem consistent
• Test your changes before submitting
• Write clear commit messages (e.g., "Add 5 new family-related words")

Not sure how to contribute? Open an issue and ask! We're here to help and appreciate all levels of contribution. Si Yu'os Ma'åse' (Thank you!) for helping preserve the Chamorro language! 🌴

Chamorro is the indigenous language of the Mariana Islands (Guam and Northern Mariana Islands). It's a vital part of the island's cultural identity and is actively preserved through education and community programs.

Resources for learning more:

• Guampedia
• Chamorro Language & Culture
• University of Guam Chamorro Studies

Want to share this gem with the world? Here's how to publish it:

• Go to rubygems.org
• Sign up (it's free!)
• Verify your email

Run gem signin and follow the prompts:

gem signin
# Enter your RubyGems.org credentials
# Give your API key a name (e.g., "CSG-RubyGems")
# When asked "Do you want to customise scopes? [yN]"
#   - Type "N" (easiest - we'll add permissions on the website)
#   - OR type "Y" and manually add scopes in the terminal

Important: By default, the API key only has "Index" permissions. You need to add Push!

1. Go to https://rubygems.org/settings/api_keys
2. Click "Edit" on the API key you just created
3. Under Scopes, check:
   • ✅ Push rubygem (required to publish - this is the one you need!)
   • ✅ Index rubygems (already checked)
   • Optional: Yank rubygem (to unpublish if needed)
4. Click "Update API Key"

You're now ready to publish! No need to sign in again.

💡 Note: If you typed "Y" in step 2 and added Push permissions in the terminal, you can skip this step!

gem build csg_chamorro.gemspec
# Creates: csg_chamorro-0.1.0.gem

gem push csg_chamorro-0.1.0.gem

You'll see:

Pushing gem to https://rubygems.org...
Successfully registered gem: csg_chamorro (0.1.0)

• Visit https://rubygems.org/gems/csg_chamorro
• Try installing: gem install csg_chamorro

Now anyone in the world can use your gem! 🌍

When you make changes:

1. Update version in lib/csg_chamorro/version.rb (e.g., 0.1.0 → 0.1.1)
2. Rebuild: gem build csg_chamorro.gemspec
3. Push: gem push csg_chamorro-0.1.1.gem

This gem was created as a learning project by students at Code School of Guam to:

• Learn Ruby gem development
• Practice version control and collaboration
• Contribute to cultural preservation
• Build portfolio-worthy projects

Learn more at https://codeschoolofguam.com

MIT License - see LICENSE.txt

Thank you for helping preserve and share the Chamorro language through technology! 🌴

Biba Guåhan! (Long live Guam!)