Integrating the New Google reCAPTCHA With YOURLS

This guide and screenshots are courtesy of Jared Stark and Erasure Web Services, originally available on their own bitty.link shortener. It’s duplicated here in case their goes offline or missing but please check on the original link first in case they have updated it. Much thanks to them!

How to integrate the New Google reCAPTCHA With YOURLS

The problem

URL shortening services are often a target for automated spam form submissions. The traditional way to prevent spam bots from doing this is to require a captcha to be properly filled out before a form can be submitted. Unfortunately, captchas can significantly reduce the quality of a user experience as they require deciphering cryptic text, putting the pieces of a puzzle together, or some other action which can significantly increase the amount of time a user spends trying to complete a form.

The new Google reCAPTCHA service aims to get rid of those traditional problems with captchas by providing what they call the “No CAPTCHA reCAPTCHA experience.” This is accomplished by using an “advanced risk analysis system” which can separate actual humans from bots with just the check of a box. More information about this system can be found on the Google reCAPTCHA website.

Because of its easy of use, the new Google reCAPTCHA is ideal for URL Shortening websites since it allows users to create short URLS quickly while preventing spam at the same time. This tutorial will show you how to integrate this service into a YOURLS installation, much like what this website, bitty.link uses.

The solution : tutorial

This tutorial will show how to implement the “No CAPTCHA reCAPTCHA” into the default YOURLS public interface setup. Obviously, it can be tweaked and modified for other public interfaces.

Please note that this tutorial uses the reCAPTCHA API 1.0.

  1. Visit the Google reCAPTCHA website. You will need to “Get reCAPTCHA,” which requires a Google account. After filling out the required information, you should receive your site key and secret key. Make sure to keep this information handy.
  2. In your YOURLS installation, open the file includes/functions-html.php. Copy the JavaScript client-side script from the reCAPTCHA website and place it in the described place (screenshot)
  3. Open your public interface file. On the reCAPTCHA website, copy the “sitekey” line and paste it in the described place (screenshot)
  4. Upload a copy of the captcha.php and recaptchalib.php files to the directory of your YOURLS installation that has your public user interface in it. Although those two files do not use the most recent reCAPTCHA API, they are easier to implement and will still work just fine.
  5. In the captcha.php file, paste in your secret and site keys to the indicated spots.
  6. Open your public user interface file. Paste the following under where it says “Part to be executed if FORM has been submitted:” include('captcha.php'); if ($resp != null && $resp->success) { (screenshot)
  7. Place a } at the end of the text block in the example photo: (screenshot)

This is the most basic way to get the new Google reCAPTCHA working on your YOURLS instillation. Although it will prevent spam bots from submitting automated requests, if a user fails to fill out the captcha, unfortunately, a reason to why the request failed will not be given unless more code is added.

Tutorial written by Jared Stark for bitty.link

Short URL to this post: http://yourls.org/di

Workshop: How to create your own translation file for YOURLS

Version 1.6 YOURLS is fully “localizable”, ie translatable, and the translation process itself is very simple. We’re going to create a translation file, but first, a very little theory.

A… “locale” ?

The default language of YOURLS is U.S. English (or, to be accurate and fair, it’s “Ozh English”: it’s not my mother tongue so a few sentences may be sometimes a bit le suck ; if so please correct me :)

In nerd speak, that language is called a “locale”: a combination of language (English) and regional dialect (US, you know, colors and colours). Hence, the default locale of YOURLS is en_US.

YOURLS uses translation files that contain the strings in English and in their translated form. There are 2 files: a PO file, which is human readable, and a MO file, which needs to be generated by a script or software.

In this example, I’ll show you how to generate a translation for France’s French (ie fr_FR) using Poedit, a simple PO file editor, but everything will be very similar using another desktop tool or web based tool such as PoEditor.com.

Generate your translation file

  1. Install Poedit. Small download, simple install, no configuration, cross platform, free.
  2. Download the YOURLS.pot template file, rename it to fr_FR.po
  3. Open your fr_FR.po with Poedit
  4. Optional : fill in some translation details. To do so: click Catalogue / Properties. Leave other fields untouched, you don’t need them.
    1
  5. Start translating. It’s really just about entering translated text in the Translation field. Be sure to copy any HTML tag, punctuation or seemingly cryptic bits such as %s that will be replaced within YOURLS by non translatable text (a URL for instance).
    2
  6. Once you’re done, save your work: Poedit will save your modified fr_FR.po file, which is the human readable translation file, and will generate a fr_FR.mo file, a machine readable file and what YOURLS need to translate strings.

YOURLS 1.6 contains about 270 translatable strings. Some are very short (one or a couple of words), some a longer sentences, but overall the process isn’t too long or cumbersome. As an example, creating the complete French translation, fine tuning it (and fixing a couple YOURLS bugs by the way) then creating a repository to host the files took me roughly 75 minutes.

Check and fine tune your translation file

Test your file to check translations perfectly fit the context they are used in:

  1. in your config.php, add or edit the following:
    define( 'YOURLS_LANG', 'fr_FR' );
  2. drop the two PO and MO files in user/languages
  3. Play with YOURLS and check all pages and possible uses (shorten link, edit and delete stuff, etc…)

Distribute your files

Last step: make sure others can benefit from you hard work!

  1. Upload your two PO and MO files somewhere on the interweb. I recommend using a source controlled service, such as Google Code or Github: this will make your changes easy to track, your files easy to maintain, and others’ contributions easy to implement. If you don’t want to use SVN or Git, a regular hosting (your blog) will be fine
  2. Ping me! Open a new issue on YOURLS.pot and tell us where your translation lives. It must be a directory, or a page listing available translations, not a specific single file.

A list of available translations will be maintained.

Protips: what makes a good translation ?

Be fluent.
To be a good translator, you need to be very comfortable with English and the language you’ll translate to. Casual knowledge of one or both will result in a translation that will most likely sound awkward or unnatural to native speakers. In other words: this.

Don’t translate literally.
Maybe the English sentence will have a 2 part structure that won’t sound natural in your language, maybe a longer sentence or 3 smaller sentences will sound better. Adapt, refine, make it sound natural.

Keep the same tone
Some messages are very formal (eg “URL invalid” as an operation result) and some are less formal. Keep the same level of formality or informality, as it depends on the context in which string will be used.

Don’t over translate.
Some English words have become common enough that it may sound weird to translate them. For instance, it’s up to you to determine if “plugin” or “bookmarklet” have to be translated or if those words are better as is.

Bonus: Protips using Poedit

Hitting Control + Enter or Control + Down arrow will navigate to the next untranslated string. Hitting Control B will copy the source (untranslated) text to the Translation box, which can be handy if you have a few HTML tags to re-use.

Sometimes the Translation field will show a split field: it means you need to enter the singular and plural form of a sentence.
3

Sometimes you will also get a few hints in the Notes for translators area: these comments will help you understand the context of a string and help you pick the best translation.
4

Short URL to this post: http://yourls.org/al

How to use Twitterfeed with your custom YOURLS URL shortener

For many, Twitterfeed means you have to use bitly. See, it is very easy to set up Twitterfeed to use your own YOURLS install and effortlessly publish tweets from a custom RSS feed using your own URL shortener. For instance, I do this on the @yourls account, where every source commit on the project gets tweeted.

Twitterfeed + custom URL shortener

To do so, create a new feed on Twitterfeed, and in the Advanced Settings, check “Post Link” and pick “Custom” as “Shorten link through” option. You’ll be given an input field to define your “Custom endpoint”. In this field, enter the URL of your YOURLS API, like so:

http://sho.rt/yourls-api.php?signature=123456&action=shorturl&format=simple&url=%@

The important bits in this URL endpoint are:

  • the URL of your YOURLS API, obviously
  • your own secret signature
  • url=%@, because Twitterfeed will replace “%@” with the URL to shorten

Twitterfeed Advanced Settings

Have fun!

Short URL to this post: http://yourls.org/3o

YOURLS Plugin Example: Conditional Toolbar

Today a YOURLS users expressed an interesting request:

Hello, I’d like to show a toolbar for, say, http://sho.rt/b when I enter the address http://sho.rt/t/b.
Is there any fast modification I can make on the toolbar sample to make this work?

Of course there is :) Thanks to the plugin API within YOURLS, this is easily feasible, and this would also be an interesting plugin poking with various areas of YOURLS code, so I thought it deserved a little blog post about it.
Continue reading

Short URL to this post: http://yourls.org/f